6693e25 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

update ames docs

6693e25tinnus-napbus5 years ago

content/docs/arvo/ames/_index.md+20

compare with master

unifiedsplit

@@ -5,3 +5,23 @@ sort_by = "weight"

5template = "sections/docs/chapters.html"

6insert_anchor_links = "right"

7+++

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 @@

1+++

2title = "Cryptography"

3−weight = 5

3+weight = 2

4template = "doc.html"

5+++

@@ -34,7 +34,7 @@ Algorithm](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algori

34is used for authentication

36The 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

38[Ames](/docs/arvo/ames/ames) for more information on packet structure). The

39message fragment is signed using the authentication key. It is encrypted using

40[`+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

43## Diffie-Hellman key exchange {#key-exchange}

45For 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

47`@uw`) is utilized for encrypting all Ames packets shared between the two ships.

48The `symmetric-key` is derived using [`+shar:ed:crypto`](/docs/arvo/reference/cryptography#ed) found in `sys/zuse.hoon`,

49which 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++++

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

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.

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

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])`.

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

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.

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.