@@ -0,0 +1,284 @@
2+title = "Ames Public API"
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.
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.
16+Ames `task`s can be naturally divided into two categories: messaging tasks and
17+system/lifecycle tasks.
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`.
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.
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).
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.
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.
57+Stop tracking a peer by sending Ames a
67+The ship to be tracked.
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.
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
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).
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.
100+`%jilt` stops tracking a potentially unresponsive peer that was previously being
101+tracked as a result of the `%heed` `task`.
103+There are two `+on-jilt` arms, this `task` utilizes `on-hear:event-core`.
111+The `ship` we no longer wish to track.
115+This `task` returns no `gift`s.
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.
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
133+A `%plea` `task` takes in the `ship` the `plea` is addressed to, and a `$plea`,
137+ +$ plea [vane=@tas =path payload=*]
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.
144+This `task` returns no `gift`s.
147+## System and Lifecycle Tasks
151+Each time you start your Urbit, the Arvo kernel calls the `%born` task for Ames.
155+`%born` takes no arguments.
159+In response to a `%born` `task`, Ames `%give`s Jael a `%turf` `gift`.
164+`%crud` is called whenever an error involving Ames occurs. It produces a crash
173+A `$error` is a `[tag=@tas =tang]`.
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`.
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.
188+In response to receiving the `%init` `task`, Ames subscribes to the information
197+`%init` takes in the name of our ship, which is a `@p`.
202+ =~ (emit duct %pass /turf %j %turf ~)
203+ (emit duct %pass /private-keys %j %private-keys ~)
206+`%init` sends two moves that subscribe to `%turf` and `%private-keys` in Jael.
211+This `task` filters debug output by ship.
219+The list of ships for which debug output is desired.
223+This `task` returns no `gift`s.
228+Sets verbosity toggles on debug output. These toggles are as follows.
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
238+Each toggle is a flag set to `%.n` by default.
246+`%spew` takes in a `list` of `verb`, which are verbosity flags for Ames.
249++$ verb ?(%snd %rcv %odd %msg %ges %for %rot)
252+`%spew` flips each toggle given in `verbs`.
256+This `task` returns no `gift`s.
261+`%vega` is called whenever the kernel is updated. Ames currently does not do
262+anything in response to this.
266+`%vega` takes no arguments.
270+This `task` returns no `gift`s.
275+This `task` is a request to Ames to produce a memory usage report.
279+This `task` has no arguments.
283+In response to this `task,` Ames `%give`s a `%mass` `gift` containing Ames'
284+current memory usage.