git.iko.soy/urbit.org
on master help sign in
Merge pull request #798 from tinnus-napbus/update-ames-docs

update ames docs

commit2d47252668c2dabf045cb9e680d33663603b5e78 authorpoprox <51337059+drbeefsupreme@users.noreply.github.com> dateMon 4 Oct 2021, 16:35 (5 years ago) parent7802dc80d139d3
6 files changed+731−295
compare with master
unifiedsplit
content/docs/arvo/ames/_index.md+20 content/docs/arvo/ames/ames-api.md−292 content/docs/arvo/ames/cryptography.md+3−3 content/docs/arvo/ames/data-types.md+389 content/docs/arvo/ames/scry.md+126 content/docs/arvo/ames/tasks.md+193
content/docs/arvo/ames/_index.md+20
@@ -5,3 +5,23 @@ sort_by = "weight"
55template = "sections/docs/chapters.html"
66insert_anchor_links = "right"
77+++
8+
9+## [Overview](/docs/arvo/ames/ames)
10+
11+An overview of Ames and its capabilities.
12+
13+## [Cryptography](/docs/arvo/ames/cryptography)
14+
15+A technical overview of how Ames implements cryptography.
16+
17+## [API Reference](/docs/arvo/ames/tasks)
18+
19+The `task`s Ames takes and the `gift`s it returns.
20+
21+## [Scry Reference](/docs/arvo/ames/scry)
22+
23+The scry endpoints of Ames.
24+
25+## [Data Types](/docs/arvo/ames/data-types)
26+
27+Reference documentation of the various data types used by Ames.
content/docs/arvo/ames/ames-api.mddeleted−292
@@ -1,292 +0,0 @@
1−+++
2−title = "API Reference"
3−weight = 10
4−template = "doc.html"
5−+++
6−
7−In this document we describe the public interface for Ames. Namely, we describe
8−each `task` that Ames can be `%pass`ed, and which `gift`(s) Ames can `%give` in return.
9−
10−Some `task`s appear to have more than one arm associated to them, e.g. there are
11−four `+on-hear` arms. We denote this where it occurs, but always refer to the
12−`on-hear:event-core` arm.
13−
14−Ames `task`s can be naturally divided into two categories: messaging tasks and
15−system/lifecycle tasks.
16−
17−## Messaging Tasks
18−
19−### `%hear`
20−
21−`%hear` handles raw packet receipt. This `task` only ever originates from Unix.
22−It does the initial processing of a packet, namely by passing the raw packet
23−information to `+decode-packet` which deserializes the packet and giving that data and the origin of the
24−packet to `+on-hear-packet`, which begins the transformation of the packet into
25−a new event in the form of a `+event-core`.
26−
27−There are multiple `+on-hear` arms in `ames.hoon`. Here we refer to
28−`on-hear:event-core`, as that is the one called by a `%hear` `task`. The other ones are used
29−primarily for ack and nack processing, or receiving message fragments.
30−
31−#### Accepts
32−
33−```hoon
34−[=lane =blob]
35−```
36−
37−`%hear` takes in a `blob`, which is essentially a large atom (around 1kB or less)
38−that is the raw data of the message, and a `lane`, which is the origin of the
39−message (typically an IP address).
40−
41−#### Returns
42−
43−`%hear` can trigger a number of possible returns. It can trigger the release of
44−zero or more additional packets via `%send` `gift`s. It may also trigger a `%boon`
45−or `%plea` `gift` (collectively referred to as a `%memo` within Ames) to a local vane in the case of a completed message.
46−
47−
48−### `%heed`
49−
50−A vane can pass Ames a `%heed` `task` to request Ames track a peer's
51−responsiveness. If our `%boon`s to it start backing up locally,
52−Ames will `give` a `%clog` back to the requesting vane containing the
53−unresponsive peer's Urbit address.
54−
55−Stop tracking a peer by sending Ames a
56−`%jilt` `task`.
57−
58−
59−#### Accepts
60−
61−```hoon
62−=ship
63−```
64−
65−The ship to be tracked.
66−
67−#### Returns
68−
69−If the `ship` is indeed being unresponsive, as measured by backed up `%boon`s,
70−Ames will `give` a `%clog` `gift` to the requesting vane containing the
71−unresponsive peer's urbit address.
72−
73−
74−### `%hole`
75−
76−`%hole` handles packet crash notification. `%hole` works much like `%hear`, in
77−that it passes an incoming raw packet to `+decode-packet` to be deserialized,
78−and then passes that data along with the source of the packet to
79−`+on-hear-packet` along with a `?` set to `%.n` denoting that there is something wrong with
80−the packet.
81−
82−#### Accepts
83−
84−```hoon
85−[=lane =blob]
86−```
87−`%hole` takes in a `blob`, which is essentially a large atom (around 1kB or less)
88−that is the raw data of the message, and a `lane`, which is the origin of the
89−message (typically an IP address).
90−
91−#### Returns
92−
93−Like `%hear`, `%hole` can trigger additional packets in the form of `%send`
94−`gift`s, and may also yield a `%boon` or `%plea` `gift` to a local vane.
95−
96−
97−### `%jilt`
98−
99−`%jilt` stops tracking a potentially unresponsive peer that was previously being
100−tracked as a result of the `%heed` `task`.
101−
102−There are two `+on-jilt` arms, this `task` utilizes `on-hear:event-core`.
103−
104−#### Accepts
105−
106−```hoon
107−=ship
108−```
109−
110−The `ship` we no longer wish to track.
111−
112−#### Returns
113−
114−This `task` returns no `gift`s.
115−
116−
117−### `%plea`
118−
119−`%plea` is the `task` used to instruct Ames to send a message. It extends the
120−`%pass`/`%give` semantics across the network. As such, it is the most
121−fundamental `task` in Ames and the primary reason for its existence.
122−
123−Ames also `pass`es a `%plea` `note` to another vane when it receives a message on a
124−"forward flow" from a peer, originally passed from one of the peer's vanes to the
125−peer's Ames.
126−
127−Ultimately `%plea` causes `%send` `gift`(s) to be sent to Unix, which tells
128−Unix to send packets. In terms of `%pass`/`%give` semantics, this is in
129−response to the `%born` `task`, which came along the Unix `duct`, rather than a
130−response to the `%plea`.
131−
132−#### Accepts
133−
134−```hoon
135−[=ship =plea]
136−```
137−
138−A `%plea` `task` takes in the `ship` the `plea` is addressed to, and a `$plea`,
139−which is
140−
141−```hoon
142− +$ plea [vane=@tas =path payload=*]
143−```
144−Here, `vane` is the destination vane on the remote ship, `path` is the internal
145−route on the receiving ship, and `payload` is the semantic message content.
146−
147−#### Returns
148−
149−This `task` returns no `gift`s.
150−
151−## System and Lifecycle Tasks
152−
153−### `%born`
154−
155−Each time you start your Urbit, the Arvo kernel calls the `%born` task for Ames.
156−
157−#### Accepts
158−
159−`%born` takes no arguments.
160−
161−#### Returns
162−
163−In response to a `%born` `task`, Ames `%give`s Jael a `%turf` `gift`.
164−
165−The `duct` along which `%born` comes is Ames' only duct to Unix, so `%send`
166−`gift`s (which are instructions for Unix to send a packet) are also returned in
167−response to `%born`.
168−
169−
170−### `%crud`
171−
172−`%crud` is called whenever an error involving Ames occurs. It produces a crash
173−report in response.
174−
175−#### Accepts
176−
177−```hoon
178−=error
179−```
180−
181−A `$error` is a `[tag=@tas =tang]`.
182−
183−#### Returns
184−
185−Ames does not `give` a `gift` in response to a `%crud` `task`, but it does
186−`%pass` Dill a `%flog` `task` instructing it to print `error`.
187−
188−
189−## `%init`
190−
191−`%init` is called a single time during the very first boot process, immediately
192−after the [larval stage](/docs/arvo/overview#larval-stage-core)
193−is completed. This initializes the vane. Jael is initialized first, followed by
194−other vanes such as Ames.
195−
196−In response to receiving the `%init` `task`, Ames subscribes to the information
197−contained by Jael.
198−
199−#### Accepts
200−
201−```hoon
202−our=ship
203−```
204−
205−`%init` takes in the name of our ship, which is a `@p`.
206−
207−#### Returns
208−
209−```hoon
210− =~ (emit duct %pass /turf %j %turf ~)
211− (emit duct %pass /private-keys %j %private-keys ~)
212−```
213−
214−`%init` sends two moves that subscribe to `%turf` and `%private-keys` in Jael.
215−
216−
217−### `%sift`
218−
219−This `task` filters debug output by ship.
220−
221−#### Accepts
222−
223−```hoon
224−ships=(list ship)
225−```
226−
227−The list of ships for which debug output is desired.
228−
229−#### Returns
230−
231−This `task` returns no `gift`s.
232−
233−
234−### `%spew`
235−
236−Sets verbosity toggles on debug output. These toggles are as follows.
237−
238−* `%snd` - sending packets
239−* `%rcv` - receiving packets
240−* `%odd` - unusual events
241−* `%msg` - message-level events
242−* `%ges` - congestion control
243−* `%for` - packet forwarding
244−* `%rot` - routing attempts
245−
246−Each toggle is a flag set to `%.n` by default.
247−
248−#### Accepts
249−
250−```hoon
251−verbs=(list verb)
252−```
253−
254−`%spew` takes in a `list` of `verb`, which are verbosity flags for Ames.
255−
256−```hoon
257−+$ verb ?(%snd %rcv %odd %msg %ges %for %rot)
258−```
259−
260−`%spew` flips each toggle given in `verbs`.
261−
262−#### Returns
263−
264−This `task` returns no `gift`s.
265−
266−
267−### `%vega`
268−
269−`%vega` is called whenever the kernel is updated. Ames currently does not do
270−anything in response to this.
271−
272−#### Accepts
273−
274−`%vega` takes no arguments.
275−
276−#### Returns
277−
278−This `task` returns no `gift`s.
279−
280−
281−### `%wegh`
282−
283−This `task` is a request to Ames to produce a memory usage report.
284−
285−#### Accepts
286−
287−This `task` has no arguments.
288−
289−#### Returns
290−
291−In response to this `task,` Ames `%give`s a `%mass` `gift` containing Ames'
292−current memory usage.
content/docs/arvo/ames/cryptography.md+3−3
@@ -1,6 +1,6 @@
11+++
22title = "Cryptography"
3−weight = 5
3+weight = 2
44template = "doc.html"
55+++
66
@@ -34,7 +34,7 @@ Algorithm](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algori
3434is used for authentication
3535
3636The encrypted payload of each packet is a `$shut-packet`, which is the `+jam` of
37−a cell with the `bone`, message number, and message fragment or ack (see
37+a cell with the [$bone](/docs/arvo/ames/data-types#bone), message number, and message fragment or ack (see
3838[Ames](/docs/arvo/ames/ames) for more information on packet structure). The
3939message fragment is signed using the authentication key. It is encrypted using
4040[`+en:crub:crypto`](/docs/arvo/reference/cryptography#en) found in
@@ -43,7 +43,7 @@ message fragment is signed using the authentication key. It is encrypted using
4343## Diffie-Hellman key exchange {#key-exchange}
4444
4545For each foreign ship a given ship has communicated with, `$ames-state` contains a
46−`$peer-state`, inside which the `$symmetric-key` (an atom which nests under
46+[$peer-state](/docs/arvo/ames/data-types#peer-state), inside which the [$symmetric-key](/docs/arvo/ames/data-types#symmetric-key) (an atom which nests under
4747`@uw`) is utilized for encrypting all Ames packets shared between the two ships.
4848The `symmetric-key` is derived using [`+shar:ed:crypto`](/docs/arvo/reference/cryptography#ed) found in `sys/zuse.hoon`,
4949which is an arm utilized for generating the symmetric key for elliptic curve
content/docs/arvo/ames/data-types.mdnew file+389
@@ -0,0 +1,389 @@
1++++
2+title = "Data Types"
3+weight = 5
4+template = "doc.html"
5++++
6+
7+Here are the data types used by Ames, as defined in `lull.hoon`.
8+
9+## `$address`
10+
11+```hoon
12++$ address @uxaddress
13+```
14+
15+Opaque atomic transport address to or from Unix. For Ames over UDP, it will encode the IP address and port.
16+
17+## `$verb`
18+
19+```hoon
20++$ verb ?(%snd %rcv %odd %msg %ges %for %rot)
21+```
22+
23+Verbosity flag for Ames. Use with `|ames-verb %flag1 %flag2 ...` and turn off with `|ames-verb`.
24+
25+- `%snd` - Sending packets.
26+- `%rcv` - Receiving packets.
27+- `%odd` - Unusual events.
28+- `%msg` - Message-level events.
29+- `%ges` - Congestion control.
30+- `%for` - Packet forwarding.
31+- `%rot` - Routing attempts.
32+
33+## `$blob`
34+
35+```hoon
36++$ blob @uxblob
37+```
38+
39+Raw atom to or from Unix, representing a packet.
40+
41+## `$error`
42+
43+```hoon
44++$ error [tag=@tas =tang]
45+```
46+
47+Tagged diagnostic trace.
48+
49+## `$lane`
50+
51+```hoon
52++$ lane (each @pC address)
53+```
54+
55+Ship transport address; either opaque [$address](#address) or galaxy. The runtime knows how to look up galaxies, so we don't need to know their transport addresses.
56+
57+## `$plea`
58+
59+```hoon
60++$ plea [vane=@tas =path payload=*]
61+```
62+
63+Application-level message, as a `%pass`.
64+
65+- `vane` - Destination vane on remote ship.
66+- `path` - Internal route on the receiving ship.
67+- `payload` - Semantic message contents.
68+
69+## `$bone`
70+
71+```hoon
72++$ bone @udbone
73+```
74+
75+Message flow index - mapped to `duct`s in the [$ossuary](#ossuary).
76+
77+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).
78+
79+The least significant bit of a `bone` is:
80+
81+- 1 if "forward", i.e. we send `%plea`s on this flow.
82+- 0 if "backward", i.e. we receive `%plea`s on this flow.
83+
84+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 `%boon`s.
85+
86+## `$fragment`
87+
88+```hoon
89++$ fragment @uwfragment
90+```
91+
92+A message fragment.
93+
94+## `$fragment-num`
95+
96+```hoon
97++$ fragment-num @udfragmentnum
98+```
99+
100+Message fragment count.
101+
102+## `$message-blob`
103+
104+```hoon
105++$ message-blob @udmessageblob
106+```
107+
108+Unfragmented message blob.
109+
110+## `$message-num`
111+
112+```hoon
113++$ message-num @udmessagenum
114+```
115+
116+Message count.
117+
118+## `$public-key`
119+
120+```hoon
121++$ public-key @uwpublickey
122+```
123+
124+A peer's public key.
125+
126+## `$symmetric-key`
127+
128+```hoon
129++$ symmetric-key @uwsymmetrickey
130+```
131+
132+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.
133+
134+## `$ack`
135+
136+```hoon
137++$ ack
138+ $% [%ok ~]
139+ [%nack ~]
140+ [%naxplanation =error]
141+ ==
142+```
143+
144+A message acknowledgement.
145+
146+- `%ok` - Positive acknowledgement.
147+- `%nack` - Negative acknowledgement.
148+- `%naxplanation` - Nack trace.
149+
150+## `$ship-state`
151+
152+```hoon
153++$ ship-state
154+ $% [%alien alien-agenda]
155+ [%known peer-state]
156+ ==
157+```
158+
159+All Ames knows about a peer.
160+
161+- `%alien` - No PKI data, so enqueue actions to perform once we learn it.
162+- `%known` - We know their `life` and public keys, so we have a channel.
163+
164+## `$alien-agenda`
165+
166+```hoon
167++$ alien-agenda
168+ $: messages=(list [=duct =plea])
169+ packets=(set =blob)
170+ heeds=(set duct)
171+ ==
172+```
173+
174+What to do when Ames learns a peer's life and keys.
175+
176+- `messages` - [$plea](#plea)s local vanes have asked Ames to send.
177+- `packets` - Packets we've tried to send.
178+- `heeds` - Local tracking requests; passed through into [$peer-state](#peer-state).
179+
180+## `$peer-state`
181+
182+```hoon
183++$ peer-state
184+ $: $: =symmetric-key
185+ =life
186+ =public-key
187+ sponsor=ship
188+ ==
189+ route=(unit [direct=? =lane])
190+ =qos
191+ =ossuary
192+ snd=(map bone message-pump-state)
193+ rcv=(map bone message-sink-state)
194+ nax=(set [=bone =message-num])
195+ heeds=(set duct)
196+ ==
197+```
198+
199+State for a peer with known life and keys.
200+
201+- `route` - Transport-layer destination for packets to the peer.
202+- `qos` - Quality of service; connection status to the peer.
203+- `ossuary` - [$bone](#bone) to `duct` mapper.
204+- `snd` - Per-`bone` message pumps to send messages as fragments.
205+- `rcv` - Per-`bone` message sinks to assemble messages from fragments.
206+- `nax` - Unprocessed nacks (negative acknowledgments).
207+- `heeds` - Listeners for `%clog` notifications.
208+
209+## `$qos`
210+
211+```hoon
212++$ qos
213+ $~ [%unborn *@da]
214+ [?(%live %dead %unborn) last-contact=@da]
215+```
216+
217+Quality of service; how is the connection to a peer doing?
218+
219+- `%live` - Peer is ok.
220+- `%dead` - Peer is not responding.
221+- `%unborn` - Peer is sunken.
222+- `last-contact` - Last time Ames heard from the peer, or if `%unborn`, the time when we first started tracking then.
223+
224+## `$ossuary`
225+
226+```hoon
227++$ ossuary
228+ $: =next=bone
229+ by-duct=(map duct bone)
230+ by-bone=(map bone duct)
231+ ==
232+```
233+
234+[$bone](#bone) to `duct` mapping, `next` is the next `bone` to map to a `duct`.
235+
236+## `$message-pump-state`
237+
238+```hoon
239++$ message-pump-state
240+ $: current=_`message-num`1
241+ next=_`message-num`1
242+ unsent-messages=(qeu message-blob)
243+ unsent-fragments=(list static-fragment)
244+ queued-message-acks=(map message-num ack)
245+ =packet-pump-state
246+ ==
247+```
248+
249+Persistent state for a `|message-pump`.
250+
251+- `current`- Sequence number of earliest message sent or being sent.
252+- `next` - Sequence number of next message to send.
253+- `unsent-messages` - Messages to be sent after current message.
254+- `unsent-fragments` - Fragments of current message waiting for sending.
255+- `queued-message-acks` - Future message acks to be applied after current.
256+- `packet-pump-state` - State of corresponding `|packet-pump`.
257+
258+## `$static-fragment`
259+
260+```hoon
261++$ static-fragment
262+ $: =message-num
263+ num-fragments=fragment-num
264+ =fragment-num
265+ =fragment
266+ ==
267+```
268+
269+A packet; a fragment of a message and metadata.
270+
271+## `$packet-pump-state`
272+
273+```hoon
274++$ packet-pump-state
275+ $: next-wake=(unit @da)
276+ live=(tree [live-packet-key live-packet-val])
277+ metrics=pump-metrics
278+ ==
279+```
280+
281+Persistent state for a `|packet-pump`.
282+
283+- `next-wake` - Last timer we've set, or null.
284+- `live` - Packets in flight; sent but not yet acked.
285+- `metrics` - Congestion control information.
286+
287+## `$pump-metrics`
288+
289+```hoon
290++$ pump-metrics
291+ $: rto=_~s1
292+ rtt=_~s1
293+ rttvar=_~s1
294+ ssthresh=_10.000
295+ cwnd=_1
296+ num-live=@ud
297+ counter=@ud
298+ ==
299+```
300+
301+Congestion control state for a `|packet-pump`.
302+
303+- `rto` - Retransmission timeout.
304+- `rtt` - Roundtrip time estimate, low-passed using EWMA.
305+- `rttvar` - Mean deviation of `rtt`, also low-passed with EWMA.
306+- `num-live` - How many packets sent, awaiting ack.
307+- `ssthresh` - Slow-start threshold.
308+- `cwnd` - Congestion window; max unacked packets.
309+
310+## `$live-packet`
311+
312+```hoon
313++$ live-packet
314+ $: key=live-packet-key
315+ val=live-packet-val
316+ ==
317+```
318+
319+A packet in flight, as tracked in the [$packet-pump-state](#packet-pump-state).
320+
321+## `$live-packet-key`
322+
323+```hoon
324++$ live-packet-key
325+ $: =message-num
326+ =fragment-num
327+ ==
328+```
329+
330+Identifier of a packet in flight.
331+
332+## `$live-packet-val`
333+
334+```hoon
335++$ live-packet-val
336+ $: packet-state
337+ num-fragments=fragment-num
338+ =fragment
339+ ==
340+```
341+
342+Content and metadata about a packet in flight.
343+
344+## `$packet-state`
345+
346+```hoon
347++$ packet-state
348+ $: last-sent=@da
349+ retries=@ud
350+ skips=@ud
351+ ==
352+```
353+
354+Sending statistics about a packet in flight.
355+
356+## `$message-sink-state`
357+
358+```hoon
359++$ message-sink-state
360+ $: last-acked=message-num
361+ last-heard=message-num
362+ pending-vane-ack=(qeu [=message-num message=*])
363+ live-messages=(map message-num partial-rcv-message)
364+ nax=(set message-num)
365+ ==
366+```
367+
368+State of a `|message-sink` to assemble received messages.
369+
370+- `last-acked` - Highest [$message-num](#message-num) Ames has fully acknowledged.
371+- `last-heard` - Highest `message-num` Ames has heard all fragments for.
372+- `pending-vane-ack` - Heard but not processed by local vane.
373+- `live-messages` - Partially received messages.
374+
375+## `$partial-rcv-message`
376+
377+```hoon
378++$ partial-rcv-message
379+ $: num-fragments=fragment-num
380+ num-received=fragment-num
381+ fragments=(map fragment-num fragment)
382+ ==
383+```
384+
385+A message for which Ames has received some fragments.
386+
387+- `num-fragments` - Total number of fragments in the message.
388+- `num-received` - How many fragments Ames has received so far.
389+- `fragments` - The received fragments themselves.
content/docs/arvo/ames/scry.mdnew file+126
@@ -0,0 +1,126 @@
1++++
2+title = "Scry Reference"
3+weight = 4
4+template = "doc.html"
5++++
6+
7+Here are the scry endpoints of Ames. All of them take a `%x` `care` and require the `desk` in the path prefix be empty, so the general format is `.^([type] %ax /=//=/[some-path])`.
8+
9+## /protocol/version
10+
11+A scry with a `%x` `care` and a `path` of `/protocol/version` will return the current Ames protocol version as a `@`.
12+
13+#### Example
14+
15+```
16+> .^(@ %ax /=//=/protocol/version)
17+0
18+```
19+
20+## /peers
21+
22+A scry with a `%x` `care` and a `path` of `/peers` will return all ships that Ames is aware of. The type returned is a `(map ship ?(%alien %known))`, where `%known` means we have PKI data for them and `%alien` means we don't.
23+
24+#### Example
25+
26+```
27+> .^((map ship ?(%alien %known)) %ax /=//=/peers)
28+{[p=~wet q=%known] [p=~nes q=%known]}
29+```
30+
31+## /peers/[ship]
32+
33+A scry with a `%x` `care` and a `path` of `/peers/[ship]` where `[ship]` is a ship name like `~dopzod` will return everything Ames knows about that ship, or crash if the ship is unknown to Ames. The type returned is a [$ship-state](/docs/arvo/ames/data-types#ship-state).
34+
35+#### Example
36+
37+```
38+> .^(ship-state:ames %ax /=//=/peers/~nes)
39+[ %known
40+ [ symmetric-key=0wEF.5-Mp4.ehBxk.a-ktl.CAUHq.~XNVq.AfPFk.TwBbj.rc7MS
41+ life=1
42+ public-key=0w9R.IG6Km.CQfuL.lP9Da.l~kh1.lOHzV.xactk.1ybiB.hekW~.VC2d0.DDRsU.h6GHl.PKmRX.p3u2-.vO4Hg.QTOlp.A4AI0.uGPVy
43+ sponsor=~nes
44+ ]
45+ route=[~ [direct=%.y lane=[%.y p=~nes]]]
46+ qos=[%dead last-contact=~2021.8.9..16.11.36..fdbc]
47+ ossuary
48+ [ next-bone=4
49+ by-duct={[p=~[/gall/sys/way/~nes/hood /gall/use/hood/0w2.4d7EV/out/~nes/hood/helm/hi/~nes /dill //term/1] q=0]}
50+ by-bone={[p=0 q=~[/gall/sys/way/~nes/hood /gall/use/hood/0w2.4d7EV/out/~nes/hood/helm/hi/~nes /dill //term/1]]}
51+ ]
52+ snd
53+ { [ p=0
54+ q
55+ [ current=2
56+ next=3
57+ unsent-messages={}
58+ unsent-fragments=~
59+ queued-message-acks={}
60+ packet-pump-state
61+ [ next-wake=[~ ~2021.8.17..02.21.14..3d23]
62+ live={[[message-num=2 fragment-num=0] [last-sent=~2021.8.17..02.19.14..3d23 retries=2.255 skips=0] num-fragments=1 fragment=0w2.QJ1qS.JzaQn.w7rMp.IzuTJ.7M7aP.-1s~1]}
63+ metrics=[rto=~m2 rtt=~s1 rttvar=~s1 ssthresh=1 cwnd=1 num-live=1 counter=1]
64+ ]
65+ ]
66+ ]
67+ }
68+ rcv={}
69+ nax={}
70+ heeds={~[/gall/sys/lag /dill //term/1]}
71+]
72+```
73+
74+## /peers/[ship]/forward-lane
75+
76+A scry with a `%x` `care` and a `path` of `/peers/[ship]/forward-lane` where `[ship]` is a ship name like `~dopzod` will return outbound routes to the given ship, or `~` if there are none. The type returned is a `(list lane:ames)`, see [$lane](/docs/arvo/ames/data-types#lane) for type details.
77+
78+#### Examples
79+
80+```
81+> .^((list lane:ames) %ax /=//=/peers/~nes/forward-lane)
82+~[[%.y p=~nes]]
83+```
84+
85+```
86+> .^((list lane:ames) %ax /=//=/peers/~nec/forward-lane)
87+~
88+```
89+
90+## /bones/[ship]
91+
92+A scry with a `%x` `care` and a `path` of `/bones/[ship]` where `[ship]` is a ship name like `~dopzod` will return inbound and outbound [$bone](/docs/arvo/ames/data-types#bone)s, which index message flows. If the ship in question is unknown to Ames, the scry will fail. The type returned is `[snd=(set bone) rcv=(set bone)]`.
93+
94+#### Example
95+
96+```
97+> .^([snd=(set bone) rcv=(set bone)] %ax /=//=/bones/~nes)
98+[snd={0} rcv={}]
99+```
100+
101+## /snd-bones/[ship]/[bone]
102+
103+A scry with a `%x` `care` and a `path` of `/snd-bones/[ship]/[bone]`, where `[ship]` is a ship name like `~dopzod` and `[bone]` is an outbound [$bone](/docs/arvo/ames/data-types#bone), will return message flow details for that `bone`. If the ship in question is unknown to Ames or the `bone` does not exist, the scry will fail. The type returned is a [$message-pump-state](/docs/arvo/ames/data-types#message-pump-state) wrapped in a `vase`.
104+
105+#### Example
106+
107+```
108+> !< message-pump-state:ames .^(vase %ax /=//=/snd-bones/~nes/0)
109+[ current=2
110+ next=3
111+ unsent-messages={}
112+ unsent-fragments=~
113+ queued-message-acks={}
114+ packet-pump-state
115+ [ next-wake=[~ ~2021.8.17..02.27.14..aaff]
116+ live
117+ { [ [message-num=2 fragment-num=0]
118+ [last-sent=~2021.8.17..02.25.14..aaff retries=2.258 skips=0]
119+ num-fragments=1
120+ fragment=0w2.QJ1qS.JzaQn.w7rMp.IzuTJ.7M7aP.-1s~1
121+ ]
122+ }
123+ metrics=[rto=~m2 rtt=~s1 rttvar=~s1 ssthresh=1 cwnd=1 num-live=1 counter=1]
124+ ]
125+]
126+```
content/docs/arvo/ames/tasks.mdnew file+193
@@ -0,0 +1,193 @@
1++++
2+title = "API Reference"
3+weight = 3
4+template = "doc.html"
5++++
6+
7+In this document we describe the public interface for Ames. Namely, we describe
8+each `task` that Ames can be `%pass`ed, and which `gift`(s) Ames can `%give` in return.
9+
10+Some `task`s appear to have more than one arm associated to them, e.g. there are
11+four `+on-hear` arms. We denote this where it occurs, but always refer to the
12+`+on-hear:event-core` arm.
13+
14+Ames `task`s can be naturally divided into two categories: messaging tasks and
15+system/lifecycle tasks.
16+
17+## Messaging Tasks
18+
19+### `%hear`
20+
21+```hoon
22+[%hear =lane =blob]
23+```
24+
25+`%hear` handles raw packet receipt.
26+
27+This `task` only ever originates from Unix. It does the initial processing of a packet, namely by passing the raw packet information to `+decode-packet` which deserializes the packet and giving that data and the origin of the packet to `+on-hear-packet`, which begins the transformation of the packet into a new event in the form of a `+event-core`.
28+
29+There are multiple `+on-hear` arms in `ames.hoon`. Here we refer to `+on-hear:event-core`, as that is the one called by a `%hear` `task`. The other ones are used primarily for ack and nack processing, or receiving message fragments.
30+
31+`%hear` takes in a [$blob](/docs/arvo/ames/data-types#blob), which is essentially a large atom (around 1kB or less) that is the raw data of the message, and a [$lane](/docs/arvo/ames/data-types#lane), which is the origin of the message (typically an IP address).
32+
33+#### Returns
34+
35+`%hear` can trigger a number of possible returns. It can trigger the release of zero or more additional packets via `%send` `gift`s. It may also trigger a `%boon` or `%plea` `gift` (collectively referred to as a `%memo` within Ames) to a local vane in the case of a completed message.
36+
37+### `%heed`
38+
39+```hoon
40+[%heed =ship]
41+```
42+
43+A vane can pass Ames a `%heed` `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.
44+
45+Stop tracking a peer by sending Ames a [%jilt](#jilt) `task`.
46+
47+The `ship` field specifies the peer to be tracked.
48+
49+#### Returns
50+
51+If the `ship` is indeed being unresponsive, as measured by backed up `%boon`s,
52+Ames will `give` a `%clog` `gift` to the requesting vane containing the
53+unresponsive peer's urbit address.
54+
55+### `%jilt`
56+
57+```hoon
58+[%jilt =ship]
59+```
60+
61+`%jilt` stops tracking a potentially unresponsive peer that was previously being
62+tracked as a result of the [%heed](#heed) `task`.
63+
64+There are two `+on-jilt` arms, this `task` utilizes `+on-hear:event-core`.
65+
66+The `ship` field specifies the peer we want to stop tracking.
67+
68+#### Returns
69+
70+This `task` returns no `gift`s.
71+
72+### `%plea`
73+
74+```hoon
75+[%plea =ship =plea:ames]
76+```
77+
78+`%plea` is the `task` used to instruct Ames to send a message. It extends the
79+`%pass`/`%give` semantics across the network. As such, it is the most
80+fundamental `task` in Ames and the primary reason for its existence.
81+
82+Ames also `pass`es a `%plea` `note` to another vane when it receives a message on a
83+"forward flow" from a peer, originally passed from one of the peer's vanes to the
84+peer's Ames.
85+
86+Ultimately `%plea` causes `%send` `gift`(s) to be sent to Unix, which tells
87+Unix to send packets. In terms of `%pass`/`%give` semantics, this is in
88+response to the `%born` `task`, which came along the Unix `duct`, rather than a
89+response to the `%plea`.
90+
91+A `%plea` `task` takes in the `ship` the `plea` is addressed to, and a [$plea](/docs/arvo/ames/data-types.md#plea).
92+
93+#### Returns
94+
95+This `task` returns no `gift`s.
96+
97+## System Tasks
98+
99+### `%born`
100+
101+```hoon
102+[%born ~]
103+```
104+
105+Each time you start your Urbit, the Arvo kernel calls the `%born` `task` for Ames.
106+
107+#### Returns
108+
109+In response to a `%born` `task`, Ames `%give`s Jael a `%turf` `gift`.
110+
111+The `duct` along which `%born` comes is Ames' only duct to Unix, so `%send`
112+`gift`s (which are instructions for Unix to send a packet) are also returned in
113+response to `%born`.
114+
115+### `%init`
116+
117+```hoon
118+[%init ~]
119+```
120+
121+`%init` is called a single time during the very first boot process, immediately
122+after the [larval stage](/docs/arvo/overview#larval-stage-core)
123+is completed. This initializes the vane. Jael is initialized first, followed by
124+other vanes such as Ames.
125+
126+In response to receiving the `%init` `task`, Ames subscribes to the information
127+contained by Jael.
128+
129+#### Returns
130+
131+```hoon
132+=~ (emit duct %pass /turf %j %turf ~)
133+ (emit duct %pass /private-keys %j %private-keys ~)
134+```
135+
136+`%init` sends two moves that subscribe to `%turf` and `%private-keys` in Jael.
137+
138+### `%sift`
139+
140+```hoon
141+[%sift ships=(list ship)]
142+```
143+
144+This `task` filters debug output by ship. This `task` is used internally when the `|ames-sift` `hood` generator is run from the dojo.
145+
146+The `ships` field specifies the ships for which debug output is desired.
147+
148+#### Returns
149+
150+This `task` returns no `gift`s.
151+
152+### `%spew`
153+
154+```hoon
155+[%spew veb=(list verb)]
156+```
157+
158+Sets verbosity toggles on debug output. This `task` is used internally when the `|ames-verb` `hood` generator is run from the dojo.
159+
160+`%spew` takes in a `list` of [$verb](/docs/arvo/ames/data-types#verb), which are verbosity flags for Ames.
161+
162+`%spew` flips each toggle given in `veb`.
163+
164+#### Returns
165+
166+This `task` returns no `gift`s.
167+
168+### `%stir`
169+
170+```hoon
171+[%stir arg=@t]
172+```
173+
174+A `%stir` `task` starts timers for any flows that lack them.
175+
176+The `arg` field is unused.
177+
178+#### Returns
179+
180+This `task` returns no `gift`s.
181+
182+### `%vega`
183+
184+```hoon
185+[%vega ~]
186+```
187+
188+`%vega` is called whenever the kernel is updated. Ames currently does not do
189+anything in response to this.
190+
191+#### Returns
192+
193+This `task` returns no `gift`s.