@@ -0,0 +1,284 @@
1++++
2+title = "Ames Public API"
3+weight = 1
4+template = "doc.html"
5++++
6+
7+# Ames
8+
9+In this document we describe the public interface for Ames. Namely, we describe
10+each `task` that Ames can be `%pass`ed, and which `gift`(s) Ames can `%give` in return.
11+
12+Some `task`s appear to have more than one arm associated to them, e.g. there are
13+four `+on-hear` arms. We denote this where it occurs, but always refer to the
14+`on-hear:event-core` arm.
15+
16+Ames `task`s can be naturally divided into two categories: messaging tasks and
17+system/lifecycle tasks.
18+
19+## Messaging Tasks
20+
21+### %hear
22+
23+`%hear` handles raw packet receipt. This `task` only ever originates from Unix.
24+It does the initial processing of a packet, namely by passing the raw packet
25+information to `+decode-packet` which deserializes the packet and giving that data and the origin of the
26+packet to `+on-hear-packet`, which begins the transformation of the packet into
27+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
30+`on-hear:event-core`, as that is the one called by a `%hear` `task`. The other ones are used
31+primarily for ack and nack processing, or receiving message fragments.
32+
33+#### Accepts
34+
35+```hoon
36+[=lane =blob]
37+```
38+
39+`%hear` takes in a `blob`, which is essentially a large atom (around 1kB or less)
40+that is the raw data of the message, and a `lane`, which is the origin of the
41+message (typically an IP address).
42+
43+#### Returns
44+
45+`%hear` can trigger a number of possible returns. It can trigger the release of
46+zero or more additional packets via `%send` `gift`s. It may also trigger a `%boon`
47+or `%plea` `gift` (collectively referred to as a `%memo` within Ames) to a local vane in the case of a completed message.
48+
49+
50+### %heed
51+
52+A vane can pass Ames a `%heed` `task` to request Ames track a peer's
53+responsiveness. If our `%boon`s to it start backing up locally,
54+Ames will `give` a `%clog` back to the requesting vane containing the
55+unresponsive peer's Urbit address.
56+
57+Stop tracking a peer by sending Ames a
58+`%jilt` `task`.
59+
60+
61+#### Accepts
62+
63+```hoon
64+=ship
65+```
66+
67+The ship to be tracked.
68+
69+#### Returns
70+
71+If the `ship` is indeed being unresponsive, as measured by backed up `%boon`s,
72+Ames will `give` a `%clog` `gift` to the requesting vane containing the
73+unresponsive peer's urbit address.
74+
75+
76+### %hole
77+
78+`%hole` handles packet crash notification. `%hole` works much like `%hear`, in
79+that it passes an incoming raw packet to `+decode-packet` to be deserialized,
80+and then passes that data along with the source of the packet to
81+`+on-hear-packet` along with a `?` set to `%.n` denoting that there is something wrong with
82+the packet.
83+
84+#### Accepts
85+
86+```hoon
87+[=lane =blob]
88+```
89+`%hole` takes in a `blob`, which is essentially a large atom (around 1kB or less)
90+that is the raw data of the message, and a `lane`, which is the origin of the
91+message (typically an IP address).
92+
93+#### Returns
94+
95+Like `%hear`, `%hole` can trigger additional packets in the form of `%send`
96+`gift`s, and may also yield a `%boon` or `%plea` `gift` to a local vane.
97+
98+### %jilt
99+
100+`%jilt` stops tracking a potentially unresponsive peer that was previously being
101+tracked as a result of the `%heed` `task`.
102+
103+There are two `+on-jilt` arms, this `task` utilizes `on-hear:event-core`.
104+
105+#### Accepts
106+
107+```hoon
108+=ship
109+```
110+
111+The `ship` we no longer wish to track.
112+
113+#### Returns
114+
115+This `task` returns no `gift`s.
116+
117+### %plea
118+
119+`%plea` is the `task` used to send messages over Ames. 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+#### Accepts
128+
129+```hoon
130+[=ship =plea]
131+```
132+
133+A `%plea` `task` takes in the `ship` the `plea` is addressed to, and a `$plea`,
134+which is
135+
136+```hoon
137+ +$ plea [vane=@tas =path payload=*]
138+```
139+Here, `vane` is the destination vane on the remote ship, `path` is the internal
140+route on the receiving ship, and `payload` is the semantic message content.
141+
142+#### Returns
143+
144+This `task` returns no `gift`s.
145+
146+
147+## System and Lifecycle Tasks
148+
149+### %born
150+
151+Each time you start your Urbit, the Arvo kernel calls the `%born` task for Ames.
152+
153+#### Accepts
154+
155+`%born` takes no arguments.
156+
157+#### Returns
158+
159+In response to a `%born` `task`, Ames `%give`s Jael a `%turf` `gift`.
160+
161+
162+### %crud
163+
164+`%crud` is called whenever an error involving Ames occurs. It produces a crash
165+report in response.
166+
167+#### Accepts
168+
169+```hoon
170+=error
171+```
172+
173+A `$error` is a `[tag=@tas =tang]`.
174+
175+#### Returns
176+
177+Ames does not `give` a `gift` in response to a `%crud` `task`, but it does
178+`%pass` Dill a `%flog` `task` instructing it to print `error`.
179+
180+
181+## %init
182+
183+`%init` is called a single time during the very first boot process, immediately
184+after the [larval stage](@/docs/tutorials/arvo/arvo.md#larval-stage-core)
185+is completed. This initializes the vane. Jael is initialized first, followed by
186+other vanes such as Ames.
187+
188+In response to receiving the `%init` `task`, Ames subscribes to the information
189+contained by Jael.
190+
191+#### Accepts
192+
193+```hoon
194+our=ship
195+```
196+
197+`%init` takes in the name of our ship, which is a `@p`.
198+
199+#### Returns
200+
201+```hoon
202+ =~ (emit duct %pass /turf %j %turf ~)
203+ (emit duct %pass /private-keys %j %private-keys ~)
204+```
205+
206+`%init` sends two moves that subscribe to `%turf` and `%private-keys` in Jael.
207+
208+
209+### %sift
210+
211+This `task` filters debug output by ship.
212+
213+#### Accepts
214+
215+```hoon
216+ships=(list ship)
217+```
218+
219+The list of ships for which debug output is desired.
220+
221+#### Returns
222+
223+This `task` returns no `gift`s.
224+
225+
226+### %spew
227+
228+Sets verbosity toggles on debug output. These toggles are as follows.
229+
230+* `%snd` - sending packets
231+* `%rcv` - receiving packets
232+* `%odd` - unusual events
233+* `%msg` - message-level events
234+* `%ges` - congestion control
235+* `%for` - packet forwarding
236+* `%rot` - routing attempts
237+
238+Each toggle is a flag set to `%.n` by default.
239+
240+#### Accepts
241+
242+```hoon
243+verbs=(list verb)
244+```
245+
246+`%spew` takes in a `list` of `verb`, which are verbosity flags for Ames.
247+
248+```hoon
249++$ verb ?(%snd %rcv %odd %msg %ges %for %rot)
250+```
251+
252+`%spew` flips each toggle given in `verbs`.
253+
254+#### Returns
255+
256+This `task` returns no `gift`s.
257+
258+
259+### %vega
260+
261+`%vega` is called whenever the kernel is updated. Ames currently does not do
262+anything in response to this.
263+
264+#### Accepts
265+
266+`%vega` takes no arguments.
267+
268+#### Returns
269+
270+This `task` returns no `gift`s.
271+
272+
273+### %wegh
274+
275+This `task` is a request to Ames to produce a memory usage report.
276+
277+#### Accepts
278+
279+This `task` has no arguments.
280+
281+#### Returns
282+
283+In response to this `task,` Ames `%give`s a `%mass` `gift` containing Ames'
284+current memory usage.