Here are the data types used by Ames, as defined in
+$ address @uxaddress
Opaque atomic transport address to or from Unix. For Ames over UDP, it will encode the IP address and port.
+$ verb ?(%snd %rcv %odd %msg %ges %for %rot)
Verbosity flag for Ames. Use with
|ames-verb %flag1 %flag2 ... and turn off with
%snd- Sending packets.
%rcv- Receiving packets.
%odd- Unusual events.
%msg- Message-level events.
%ges- Congestion control.
%for- Packet forwarding.
%rot- Routing attempts.
+$ blob @uxblob
Raw atom to or from Unix, representing a packet.
+$ error [tag=@tas =tang]
Tagged diagnostic trace.
+$ lane (each @pC address)
Ship transport address; either opaque $address or galaxy. The runtime knows how to look up galaxies, so we don't need to know their transport addresses.
+$ plea [vane=@tas =path payload=*]
Application-level message, as a
vane- Destination vane on remote ship.
path- Internal route on the receiving ship.
payload- Semantic message contents.
+$ bone @udbone
Message flow index - mapped to
ducts in the $ossuary.
bone is 0. They increment by 4, since each flow includes a bit for each message determining forward vs. backward and a second bit for whether the message is on the normal flow or the associated diagnostic flow (for naxplanations).
The least significant bit of a
- 1 if "forward", i.e. we send
%pleas on this flow.
- 0 if "backward", i.e. we receive
%pleas on this flow.
The second-least significant bit is 1 if the
bone is a naxplanation
bone, and 0 otherwise. Only naxplanation messages can be sent on a naxplanation
+$ fragment @uwfragment
A message fragment.
+$ fragment-num @udfragmentnum
Message fragment count.
+$ message-blob @udmessageblob
Unfragmented message blob.
+$ message-num @udmessagenum
+$ public-key @uwpublickey
A peer's public key.
+$ symmetric-key @uwsymmetrickey
A symmetric key for encrypting messages to a peer. This is produced by performing an elliptic curve Diffie-Hellman using our private key and the peer's public key.
+$ ack$% [%ok ~][%nack ~][%naxplanation =error]==
A message acknowledgement.
%ok- Positive acknowledgement.
%nack- Negative acknowledgement.
%naxplanation- Nack trace.
+$ ship-state$% [%alien alien-agenda][%known peer-state]==
All Ames knows about a peer.
%alien- No PKI data, so enqueue actions to perform once we learn it.
%known- We know their
lifeand public keys, so we have a channel.
+$ alien-agenda$: messages=(list [=duct =plea])packets=(set =blob)heeds=(set duct)==
What to do when Ames learns a peer's life and keys.
messages- $pleas local vanes have asked Ames to send.
packets- Packets we've tried to send.
heeds- Local tracking requests; passed through into $peer-state.
+$ peer-state$: $: =symmetric-key=life=public-keysponsor=ship==route=(unit [direct=? =lane])=qos=ossuarysnd=(map bone message-pump-state)rcv=(map bone message-sink-state)nax=(set [=bone =message-num])heeds=(set duct)==
State for a peer with known life and keys.
route- Transport-layer destination for packets to the peer.
qos- Quality of service; connection status to the peer.
ossuary- $bone to
bonemessage pumps to send messages as fragments.
bonemessage sinks to assemble messages from fragments.
nax- Unprocessed nacks (negative acknowledgments).
heeds- Listeners for
+$ qos$~ [%unborn *@da][?(%live %dead %unborn) last-contact=@da]
Quality of service; how is the connection to a peer doing?
%live- Peer is ok.
%dead- Peer is not responding.
%unborn- Peer is sunken.
last-contact- Last time Ames heard from the peer, or if
%unborn, the time when we first started tracking then.
+$ ossuary$: =next=boneby-duct=(map duct bone)by-bone=(map bone duct)==
next is the next
bone to map to a
+$ message-pump-state$: current=_`message-num`1next=_`message-num`1unsent-messages=(qeu message-blob)unsent-fragments=(list static-fragment)queued-message-acks=(map message-num ack)=packet-pump-state==
Persistent state for a
current- Sequence number of earliest message sent or being sent.
next- Sequence number of next message to send.
unsent-messages- Messages to be sent after current message.
unsent-fragments- Fragments of current message waiting for sending.
queued-message-acks- Future message acks to be applied after current.
packet-pump-state- State of corresponding
+$ static-fragment$: =message-numnum-fragments=fragment-num=fragment-num=fragment==
A packet; a fragment of a message and metadata.
+$ packet-pump-state$: next-wake=(unit @da)live=(tree [live-packet-key live-packet-val])metrics=pump-metrics==
Persistent state for a
next-wake- Last timer we've set, or null.
live- Packets in flight; sent but not yet acked.
metrics- Congestion control information.
+$ pump-metrics$: rto=_~s1rtt=_~s1rttvar=_~s1ssthresh=_10.000cwnd=_1num-live=@udcounter=@ud==
Congestion control state for a
rto- Retransmission timeout.
rtt- Roundtrip time estimate, low-passed using EWMA.
rttvar- Mean deviation of
rtt, also low-passed with EWMA.
num-live- How many packets sent, awaiting ack.
ssthresh- Slow-start threshold.
cwnd- Congestion window; max unacked packets.
+$ live-packet$: key=live-packet-keyval=live-packet-val==
A packet in flight, as tracked in the $packet-pump-state.
+$ live-packet-key$: =message-num=fragment-num==
Identifier of a packet in flight.
+$ live-packet-val$: packet-statenum-fragments=fragment-num=fragment==
Content and metadata about a packet in flight.
+$ packet-state$: last-sent=@daretries=@udskips=@ud==
Sending statistics about a packet in flight.
+$ message-sink-state$: last-acked=message-numlast-heard=message-numpending-vane-ack=(qeu [=message-num message=*])live-messages=(map message-num partial-rcv-message)nax=(set message-num)==
State of a
|message-sink to assemble received messages.
last-acked- Highest $message-num Ames has fully acknowledged.
message-numAmes has heard all fragments for.
pending-vane-ack- Heard but not processed by local vane.
live-messages- Partially received messages.
+$ partial-rcv-message$: num-fragments=fragment-numnum-received=fragment-numfragments=(map fragment-num fragment)==
A message for which Ames has received some fragments.
num-fragments- Total number of fragments in the message.
num-received- How many fragments Ames has received so far.
fragments- The received fragments themselves.