Here are the data types used by Ames, as defined in lull.hoon.

$address

+$  address  @uxaddress

Opaque atomic transport address to or from Unix. For Ames over UDP, it will encode the IP address and port.

$verb

+$  verb  ?(%snd %rcv %odd %msg %ges %for %rot)

Verbosity flag for Ames. Use with |ames-verb %flag1 %flag2 ... and turn off with |ames-verb.

• %snd - Sending packets.
• %rcv - Receiving packets.
• %odd - Unusual events.
• %msg - Message-level events.
• %ges - Congestion control.
• %for - Packet forwarding.
• %rot - Routing attempts.

$blob

+$  blob  @uxblob

Raw atom to or from Unix, representing a packet.

$error

+$  error  [tag=@tas =tang]

Tagged diagnostic trace.

$lane

+$  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

+$  plea  [vane=@tas =path payload=*]

Application-level message, as a %pass.

• vane - Destination vane on remote ship.
• path - Internal route on the receiving ship.
• payload - Semantic message contents.

$bone

+$  bone  @udbone

Message flow index - mapped to ducts in the $ossuary.

The first 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 bone is:

• 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 bone, as %boons.

$fragment

+$  fragment  @uwfragment

A message fragment.

$fragment-num

+$  fragment-num  @udfragmentnum

Message fragment count.

$message-blob

+$  message-blob  @udmessageblob

Unfragmented message blob.

$message-num

+$  message-num  @udmessagenum

Message count.

$public-key

+$  public-key  @uwpublickey

A peer's public key.

$symmetric-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

+$  ack
  $%  [%ok ~]
      [%nack ~]
      [%naxplanation =error]
  ==

A message acknowledgement.

• %ok - Positive acknowledgement.
• %nack - Negative acknowledgement.
• %naxplanation - Nack trace.

$ship-state

+$  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 life and public keys, so we have a channel.

$alien-agenda

+$  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

+$  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 duct mapper.
• snd - Per-bone message pumps to send messages as fragments.
• rcv - Per-bone message sinks to assemble messages from fragments.
• nax - Unprocessed nacks (negative acknowledgments).
• heeds - Listeners for %clog notifications.

$qos

+$  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

+$  ossuary
  $:  =next=bone
      by-duct=(map duct bone)
      by-bone=(map bone duct)
  ==

$bone to duct mapping, next is the next bone to map to a duct.

$message-pump-state

+$  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 |message-pump.

• 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 |packet-pump.

$static-fragment

+$  static-fragment
  $:  =message-num
      num-fragments=fragment-num
      =fragment-num
      =fragment
  ==

A packet; a fragment of a message and metadata.

$packet-pump-state

+$  packet-pump-state
  $:  next-wake=(unit @da)
      live=(tree [live-packet-key live-packet-val])
      metrics=pump-metrics
  ==

Persistent state for a |packet-pump.

• next-wake - Last timer we've set, or null.
• live - Packets in flight; sent but not yet acked.
• metrics - Congestion control information.

$pump-metrics

+$  pump-metrics
  $:  rto=_~s1
      rtt=_~s1
      rttvar=_~s1
      ssthresh=_10.000
      cwnd=_1
      num-live=@ud
      counter=@ud
  ==

Congestion control state for a |packet-pump.

• 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

+$  live-packet
  $:  key=live-packet-key
      val=live-packet-val
  ==

A packet in flight, as tracked in the $packet-pump-state.

$live-packet-key

+$  live-packet-key
  $:  =message-num
      =fragment-num
  ==

Identifier of a packet in flight.

$live-packet-val

+$  live-packet-val
  $:  packet-state
      num-fragments=fragment-num
      =fragment
  ==

Content and metadata about a packet in flight.

$packet-state

+$  packet-state
  $:  last-sent=@da
      retries=@ud
      skips=@ud
  ==

Sending statistics about a packet in flight.

$message-sink-state

+$  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.
• last-heard - Highest message-num Ames has heard all fragments for.
• pending-vane-ack - Heard but not processed by local vane.
• live-messages - Partially received messages.

$partial-rcv-message

+$  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.