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-key sponsor=ship == route=(unit [direct=? =lane]) =qos =ossuary snd=(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=bone by-duct=(map duct bone) by-bone=(map bone duct) ==
next is the next
bone to map to a
+$ message-pump-state $: current=_`message-num`1 next=_`message-num`1 unsent-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-num num-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=_~s1 rtt=_~s1 rttvar=_~s1 ssthresh=_10.000 cwnd=_1 num-live=@ud counter=@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-key val=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-state num-fragments=fragment-num =fragment ==
Content and metadata about a packet in flight.
+$ packet-state $: last-sent=@da retries=@ud skips=@ud ==
Sending statistics about a packet in flight.
+$ message-sink-state $: last-acked=message-num last-heard=message-num pending-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-num num-received=fragment-num fragments=(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.