46ec329 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

Merge pull request #1230 from tinnus-napbus/gall-add-data-types-and-restructure

46ec329poprox5 years ago

content/docs/arvo/_index.md+2−4

compare with master

unifiedsplit

@@ -36,11 +36,11 @@ Eyre is our HTTP server. Unix sends HTTP messages to `%eyre`, and `%eyre` produc

37Ford is our build system. It handles resources and publishing.

39−## [Gall](/docs/arvo/gall/overview)

39+## [Gall](/docs/arvo/gall/gall)

41Gall is the vane for controlling userspace apps.

43−## [Iris](/docs/arvo/iris/iris-api)

43+## [Iris](/docs/arvo/iris/iris)

45Iris is our HTTP client.

@@ -51,5 +51,3 @@ Explanations of design decisions that are pervasive throughout Arvo.

51## [Tutorials](/docs/arvo/tutorials/)

53Walkthroughs that teach you more about how Arvo works.

54−

55−

content/docs/arvo/ames/ames.md+74−74

@@ -4,6 +4,7 @@ weight = 1

4template = "doc.html"

5aliases = ["/docs/learn/arvo/ames/"]

6+++

7Our networking protocol.

8Our networking protocol.

9Ames is the name of both our network and the vane that communicates

10Ames is the name of both our network and the vane that communicates

@@ -11,7 +12,7 @@ over it. When Unix receives a packet over the correct UDP port, it pipes

11it straight into Ames for handling. Also, all packets sent over the

12it straight into Ames for handling. Also, all packets sent over the

12Ames network are sent by the Ames vane. Apps and vanes may use

13Ames network are sent by the Ames vane. Apps and vanes may use

13Ames to directly send messages to other ships. In general, apps use

14Ames to directly send messages to other ships. In general, apps use

14−[Gall](/docs/userspace/gall/gall) and [Clay](/docs/arvo/clay/clay)

15+[Gall](/docs/arvo/gall/gall) and [Clay](/docs/arvo/clay/clay)

15to communicate with other ships rather than using Ames

16to communicate with other ships rather than using Ames

16directly, but this isn't a requirement. Of course, Gall and Clay use

17directly, but this isn't a requirement. Of course, Gall and Clay use

17Ames behind the scenes to communicate across the network. Jael is the only other

18Ames behind the scenes to communicate across the network. Jael is the only other

@@ -25,32 +26,33 @@ protocol itself, including how to route incoming packets to the correct

25vane or app, is defined in Ames.

26vane or app, is defined in Ames.

27## Technical Overview

28## Technical Overview

29+

28This section summarizes the design of Ames. Beyond this section are deeper

30This section summarizes the design of Ames. Beyond this section are deeper

29elaborations on the concepts presented here.

31elaborations on the concepts presented here.

31Ames extends [Arvo's](/docs/arvo/overview) `%pass`/`%give` `move` semantics across the network.

33Ames extends [Arvo's](/docs/arvo/overview) `%pass`/`%give` `move` semantics across the network.

33Ames receives packets as Arvo events and emits packets as Arvo

35Ames receives packets as Arvo events and emits packets as Arvo

34−effects. The runtime is responsible for transferring the bytes in

36+effects. The runtime is responsible for transferring the bytes in

35an Ames packet across a physical network to another ship.

37an Ames packet across a physical network to another ship.

37The runtime tells Ames which physical address a packet came from,

39The runtime tells Ames which physical address a packet came from,

38−represented as an opaque atom. Ames can emit a packet effect to

40+represented as an opaque atom. Ames can emit a packet effect to

39one of those opaque atoms or to the Urbit address of a galaxy

41one of those opaque atoms or to the Urbit address of a galaxy

40(root node), which the runtime is responsible for translating to a

42(root node), which the runtime is responsible for translating to a

41−physical address. One runtime implementation sends UDP packets

43+physical address. One runtime implementation sends UDP packets

42using IPv4 addresses for ships and DNS lookups for galaxies, but

44using IPv4 addresses for ships and DNS lookups for galaxies, but

43other implementations may overlay over other kinds of networks.

45other implementations may overlay over other kinds of networks.

45−A local vane can pass Ames a `%plea` request message. Ames

47+A local vane can pass Ames a `%plea` request message. Ames

46transmits the message over the wire to the peer ship's Ames, which

48transmits the message over the wire to the peer ship's Ames, which

47passes the message to the destination vane.

49passes the message to the destination vane.

49Once the peer has processed the `%plea` message, it sends a

51Once the peer has processed the `%plea` message, it sends a

50message-acknowledgment packet over the wire back to the local

52message-acknowledgment packet over the wire back to the local

51−Ames. This "ack" can either be positive to indicate the request was

53+Ames. This "ack" can either be positive to indicate the request was

52processed, or negative to indicate the request failed, in which

54processed, or negative to indicate the request failed, in which

53−case it's called a "nack". (Don't confuse Ames nacks with TCP

55+case it's called a "nack". (Don't confuse Ames nacks with TCP

54nacks, which are a different concept).

56nacks, which are a different concept).

56When the local Ames receives either a positive message-ack or a

58When the local Ames receives either a positive message-ack or a

@@ -60,11 +62,11 @@ requested the original `%plea` message be sent.

61A local vane can give Ames zero or more `%boon` response messages in

63A local vane can give Ames zero or more `%boon` response messages in

62response to a `%plea`, on the same duct that Ames used to pass the

64response to a `%plea`, on the same duct that Ames used to pass the

63−`%plea` to the vane. Ames transmits a `%boon` over the wire to the

65+`%plea` to the vane. Ames transmits a `%boon` over the wire to the

64peer's Ames, which gives it to the destination vane on the same

66peer's Ames, which gives it to the destination vane on the same

65duct the vane had used to pass the original `%plea` to Ames.

67duct the vane had used to pass the original `%plea` to Ames.

67−`%boon` messages are acked automatically by the receiver Ames. They

69+`%boon` messages are acked automatically by the receiver Ames. They

68cannot be nacked, and Ames only uses the ack internally, without

70cannot be nacked, and Ames only uses the ack internally, without

69notifying the client vane that gave Ames the `%boon`.

71notifying the client vane that gave Ames the `%boon`.

@@ -74,15 +76,15 @@ indicating the `%boon` was missed.

75`%plea` messages can be nacked, in which case the peer will send

77`%plea` messages can be nacked, in which case the peer will send

76both a message-nack packet and a naxplanation message, which is

78both a message-nack packet and a naxplanation message, which is

77−sent in a way that does not interfere with normal operation. The

79+sent in a way that does not interfere with normal operation. The

78naxplanation is sent as a full Ames message, instead of just a

80naxplanation is sent as a full Ames message, instead of just a

79packet, because the contained error information can be arbitrarily

81packet, because the contained error information can be arbitrarily

80−large. A naxplanation can only give rise to a positive ack --

82+large. A naxplanation can only give rise to a positive ack --

81never ack an ack, and never nack a naxplanation.

83never ack an ack, and never nack a naxplanation.

83Ames guarantees a total ordering of messages within a "flow",

85Ames guarantees a total ordering of messages within a "flow",

84identified in other vanes by a duct and over the wire by a `bone`:

86identified in other vanes by a duct and over the wire by a `bone`:

85−an opaque number. Each flow has a FIFO (first-in-first-out) queue of `%plea` requests

87+an opaque number. Each flow has a FIFO (first-in-first-out) queue of `%plea` requests

86from the requesting ship to the responding ship and a FIFO queue

88from the requesting ship to the responding ship and a FIFO queue

87of `%boon`'s in the other direction.

89of `%boon`'s in the other direction.

@@ -94,23 +96,23 @@ destination vane.

95Ames encrypts every message using symmetric-key encryption by

97Ames encrypts every message using symmetric-key encryption by

96performing an elliptic curve Diffie-Hellman using our private key

98performing an elliptic curve Diffie-Hellman using our private key

97−and the public key of the peer. For ships in the Jael PKI

99+and the public key of the peer. For ships in the Jael PKI

98(public-key infrastructure), Ames looks up the peer's public key

100(public-key infrastructure), Ames looks up the peer's public key

99−from Jael. Comets (128-bit ephemeral addresses) are not

101+from Jael. Comets (128-bit ephemeral addresses) are not

100cryptographic assets and must self-attest over Ames by sending a

102cryptographic assets and must self-attest over Ames by sending a

101single self-signed packet containing their public key.

103single self-signed packet containing their public key.

102

104

103When a peer suffers a continuity breach, Ames removes all

105When a peer suffers a continuity breach, Ames removes all

104−messaging state related to it. Ames does not guarantee that all

106+messaging state related to it. Ames does not guarantee that all

105−messages will be fully delivered to the now-stale peer. From

107+messages will be fully delivered to the now-stale peer. From

106Ames's perspective, the newly restarted peer is a new ship.

108Ames's perspective, the newly restarted peer is a new ship.

107Ames's guarantees are not maintained across a breach.

109Ames's guarantees are not maintained across a breach.

108

110

109A vane can pass Ames a `%heed` `$task` to request Ames track a peer's

111A vane can pass Ames a `%heed` `$task` to request Ames track a peer's

110−responsiveness. If our `%boon`'s to it start backing up locally,

112+responsiveness. If our `%boon`'s to it start backing up locally,

111Ames will give a `%clog` back to the requesting vane containing the

113Ames will give a `%clog` back to the requesting vane containing the

112−unresponsive peer's urbit address. This interaction does not use

114+unresponsive peer's urbit address. This interaction does not use

113−ducts as unique keys. Stop tracking a peer by sending Ames a

115+ducts as unique keys. Stop tracking a peer by sending Ames a

114`%jilt` `$task`.

116`%jilt` `$task`.

115

117

116Debug output can be adjusted using `%sift` and `%spew` `$task`'s.

118Debug output can be adjusted using `%sift` and `%spew` `$task`'s.

@@ -128,46 +130,46 @@ There is a 32-bit header followed by a variable width body.

128

130

129The 32-bit header is given by the following data, presented in order:

131The 32-bit header is given by the following data, presented in order:

130

132

131− - 3 bits: reserved

133+- 3 bits: reserved

132− - 1 bit: is this Ames? (i.e. not using a different protocol, such as the

134+- 1 bit: is this Ames? (i.e. not using a different protocol, such as the

133− planned remote scry protocol)

135+ planned remote scry protocol)

134− - 3 bits: Ames protocol version (currently 0)

136+- 3 bits: Ames protocol version (currently 0)

135− - 2 bits: sender address size

137+- 2 bits: sender address size

136− - 2 bits: receiver address size

138+- 2 bits: receiver address size

137− - 20 bits: checksum (truncated insecure hash of the body, done with

139+- 20 bits: checksum (truncated insecure hash of the body, done with

138− [`+mug`](/docs/hoon/reference/stdlib/2e#mug)

140+ [`+mug`](/docs/hoon/reference/stdlib/2e#mug)

139− - 1 bit: is this relayed? (if set, `origin` will be present in the body)

141+- 1 bit: is this relayed? (if set, `origin` will be present in the body)

140

142

141− Every packet sent between ships is encrypted except for self-signed attestation packets from 128-bit comets.

143+Every packet sent between ships is encrypted except for self-signed attestation packets from 128-bit comets.

142

144

143#### Body

145#### Body

144

146

145The body is of variable length and consists of the following parts in this

147The body is of variable length and consists of the following parts in this

146order:

148order:

147

149

148− - 4 bits: sender life (mod 16)

150+- 4 bits: sender life (mod 16)

149− - 4 bits: receiver life (mod 16)

151+- 4 bits: receiver life (mod 16)

150− - variable: sender address

152+- variable: sender address

151− - variable: receiver address

153+- variable: receiver address

152− - 48 bits: (optional) 48-bit `origin`

154+- 48 bits: (optional) 48-bit `origin`

153− - 128 bits: `SIV`

155+- 128 bits: `SIV`

154− - 16 bits: ciphertext size

156+- 16 bits: ciphertext size

155− - variable: ciphertext

157+- variable: ciphertext

156−

158+

157− `origin` is the IP and port of the original sender if the packet was proxied

159+`origin` is the IP and port of the original sender if the packet was proxied

158− through a relay.

160+through a relay.

159−

161+

160− `SIV` is a "synthetic initialization vector" as defined in AES-256 SIV, the encryption

162+`SIV` is a "synthetic initialization vector" as defined in AES-256 SIV, the encryption

161− algorithm utilized to encrypt Ames packets (see the page on [Ames

163+algorithm utilized to encrypt Ames packets (see the page on [Ames

162− cryptography](/docs/arvo/ames/cryptography)). It is formed from the

164+cryptography](/docs/arvo/ames/cryptography)). It is formed from the

163− following noun: `~[sender=@p receiver=@p sender-life=@ receiver-life=@]` (see

165+following noun: `~[sender=@p receiver=@p sender-life=@ receiver-life=@]` (see

164− [Life and Rift](/docs/azimuth/life-and-rift) for information on what `life`

166+[Life and Rift](/docs/azimuth/life-and-rift) for information on what `life`

165− is). As this data is in Azimuth, it is not explicitly sent over the wire. Thus

167+is). As this data is in Azimuth, it is not explicitly sent over the wire. Thus

166− the mod 16 sender and receiver life in the first 8 bits are only for quick

168+the mod 16 sender and receiver life in the first 8 bits are only for quick

167− filtering of honest packets sent to or from a stale life.

169+filtering of honest packets sent to or from a stale life.

168−

170+

169− The ciphertext is formed by `+jam`ming a `$shut-packet` and then encrypting

171+The ciphertext is formed by `+jam`ming a `$shut-packet` and then encrypting

170− using [`+en:sivc:aes:crypto`](/docs/arvo/reference/cryptography#en).

172+using [`+en:sivc:aes:crypto`](/docs/arvo/reference/cryptography#en).

171

173

172### Packeting

174### Packeting

173

175

@@ -187,9 +189,7 @@ eventually get through, and when the other side gets them it can put them in the

187correct order. If Ames doesn't get an ack on a packet then it will resend it

189correct order. If Ames doesn't get an ack on a packet then it will resend it

188until it does. The logic for determining how many packets to send or re-send at what time is performed by an Ames-specific variant of TCP's "NewReno" congestion control algorithm.

190until it does. The logic for determining how many packets to send or re-send at what time is performed by an Ames-specific variant of TCP's "NewReno" congestion control algorithm.

189

191

190−As each packet in a message is received, Ames decrypts it and stores the message fragment. Once it's received every packet for a message, Ames concatenates the fragments back into a single large atom and uses `+cue` to deserialize that back into the original message noun.

192+As each packet in a message is received, Ames decrypts it and stores the message fragment. Once it's received every packet for a message, Ames concatenates the fragments back into a single large atom and uses `+cue` to deserialize that back into the original message noun.

191−

192−

193

194### Acks and Nacks

195

@@ -221,7 +221,6 @@ Thus a message-level ack must be received before the next message on the flow

221can begin. The full story is more complicated than this; see the section on

222[flows](#flows).

223

224−

225#### Nacks

224#### Nacks

226

225

227A nack indicates a negative acknowledgement to a `%plea`, meaning that the

226A nack indicates a negative acknowledgement to a `%plea`, meaning that the

@@ -248,9 +247,11 @@ the receiver will never both perform a `%plea` and return a naxplanation.

248

247

249A fragment ack's contents (before encryption) are a pure function of the

248A fragment ack's contents (before encryption) are a pure function of the

250following noun:

249following noun:

250+

251```hoon

252[our-life her-life bone message-num fragment-num]

253```

254+

254This means all re-sends of an ack packet will be bitwise identical to each other, unless one of the peers changes its encryption keys.

255This means all re-sends of an ack packet will be bitwise identical to each other, unless one of the peers changes its encryption keys.

255

256

256Each datum in this noun is an atom with the aura `@ud` or an aura that nests

257Each datum in this noun is an atom with the aura `@ud` or an aura that nests

@@ -269,11 +270,11 @@ A message (n)ack is a different kind of ack that is obtained by encrypting the

269```hoon

270```hoon

270[our-life her-life bone message-num ok=? lag=@dr]

271[our-life her-life bone message-num ok=? lag=@dr]

271```

272```

273+

272`ok` is a flag that is set to `%.y` for a message ack and `%.n` for a message

274`ok` is a flag that is set to `%.y` for a message ack and `%.n` for a message

273nack. In the future, `lag` will be used to

275nack. In the future, `lag` will be used to

274describe the time it took to process a message, but for now it is always zero.

276describe the time it took to process a message, but for now it is always zero.

275

277

276−

277### Flows

278### Flows

278

279

279Flows are asymmetric communication channels along which two ships send and

280Flows are asymmetric communication channels along which two ships send and

@@ -300,10 +301,10 @@ We give an example of such a partition. Let flow 12 be a flow between `~bacbel-t

300`~bacbel-tagfeg` as the `%plea` sender. Then bones 12-15 are associated with the

301`~bacbel-tagfeg` as the `%plea` sender. Then bones 12-15 are associated with the

301flow, and the types of packets for each bone are:

302flow, and the types of packets for each bone are:

302

303

303− - bone 12, `%plea`s and acks to `~worwel-sipnum`,

304+- bone 12, `%plea`s and acks to `~worwel-sipnum`,

304− - bone 13, `%boon`s and (n)acks to `~bacbel-tagfeg`,

305+- bone 13, `%boon`s and (n)acks to `~bacbel-tagfeg`,

305− - bone 14, acks of naxplanations to `~worwel-sipnum`,

306+- bone 14, acks of naxplanations to `~worwel-sipnum`,

306− - bone 15, naxplanations to `~bacbel-tagfeg`.

307+- bone 15, naxplanations to `~bacbel-tagfeg`.

307

308

308Each bone is handled separately by congestion control, and this is one reason

309Each bone is handled separately by congestion control, and this is one reason

309for their segregation. For example, say a two-packet `%plea` is sent on bone 12,

310for their segregation. For example, say a two-packet `%plea` is sent on bone 12,

@@ -379,16 +380,17 @@ private key and the public key of `~worwel-sipnum`, obtained via Jael. Then

379`~bacbel-tagfeb` sends a packet addressed to `~worwel-sipnum` to `~zod`.

380`~bacbel-tagfeb` sends a packet addressed to `~worwel-sipnum` to `~zod`.

380

381

381The packet has the following format:

382The packet has the following format:

383+

382− - The standard Ames header described in [header](#header), where the checksum

384+- The standard Ames header described in [header](#header), where the checksum

383− is the `+mug` of the body, and the sender and receiver ship types are `01`,

385+ is the `+mug` of the body, and the sender and receiver ship types are `01`,

384− denoting that the sender and receiver are planets. The "is this relayed?" bit

386+ denoting that the sender and receiver are planets. The "is this relayed?" bit

385− is set to 0 since this is the first hop on the packet route.

387+ is set to 0 since this is the first hop on the packet route.

386− - The body of this packet will be the life of `~bacbel-tagfeg` mod 16, followed

388+- The body of this packet will be the life of `~bacbel-tagfeg` mod 16, followed

387− by the life of `~worwel-sipnum` mod 16, followed by `~bacbel-tagfeg`,

389+ by the life of `~worwel-sipnum` mod 16, followed by `~bacbel-tagfeg`,

388− followed by the receiver `~worwel-sipnum`, followed by the origin `~`

390+ followed by the receiver `~worwel-sipnum`, followed by the origin `~`

389− (denoting that the ship sending the packet is the origin). After this comes

391+ (denoting that the ship sending the packet is the origin). After this comes

390− the payload.

392+ the payload.

391− - The payload of this packet will be the `+jam` of the `content`, which is an encrypted fragment of the message `%watch /path/to/recipes`.

393+- The payload of this packet will be the `+jam` of the `content`, which is an encrypted fragment of the message `%watch /path/to/recipes`.

392

394

393`~zod` receives the packet and reads the body. It sees that it is not the

395`~zod` receives the packet and reads the body. It sees that it is not the

394intended recipient of the packet, and so gets ready to forward it to

396intended recipient of the packet, and so gets ready to forward it to

@@ -398,8 +400,7 @@ with the new mug. Since the packet is being relayed, `~zod` flips the "is it

398relayed?" bit to `%.y`. `~zod` then forwards the packet to `~worwel-sipnum`.

400relayed?" bit to `%.y`. `~zod` then forwards the packet to `~worwel-sipnum`.

399

401

400In order to decrypt the packet, `~worwel-sipnum` will need to calculate the

402In order to decrypt the packet, `~worwel-sipnum` will need to calculate the

401−associated data vector utilized by SIV, which consists of `~[sender=@p

402−receiver=@p sender-life=@ receiver-life=@]`. It then passes that along with the

403+associated data vector utilized by SIV, which consists of `~[sender=@p receiver=@p sender-life=@ receiver-life=@]`. It then passes that along with the

403SIV and ciphertext to the decryption function, and receives the unencrypted

404SIV and ciphertext to the decryption function, and receives the unencrypted

404packet as a return.

405packet as a return.

405

406

@@ -463,4 +464,3 @@ hands it off the the Unix network interface to be sent.

463Now the receiving King is handed a UDP packet by Unix. The King removes the UDP

464Now the receiving King is handed a UDP packet by Unix. The King removes the UDP

464wrapper, `+jam`s the `lane` on which it heard the packet, and delivers the packet

465wrapper, `+jam`s the `lane` on which it heard the packet, and delivers the packet

465to the Ames vane as an atom by copying the bytes it heard on the UDP port.

466to the Ames vane as an atom by copying the bytes it heard on the UDP port.

466−

content/docs/arvo/concepts/scry.md+1−1

@@ -74,4 +74,4 @@ The webserver vane Eyre has a system which allows clients like web browsers to p

75[Eyre's External API Reference](/docs/arvo/eyre/external-api-ref#scry) - Documentation of Eyre's scry system which allows web clients to perform scries over HTTP.

77−[The Gall Guide](/docs/userspace/gall/tutorial) - The Gall tutorial includes a section about `+on-peek` and writing scry endpoints.

77+[The Gall Guide](/docs/userspace/gall-guide) - The Gall tutorial includes a section about `+on-peek` and writing scry endpoints.

content/docs/arvo/gall/data-types.mdnew file+492

@@ -0,0 +1,492 @@

1++++

2+title = "Data Types"

3+weight = 5

4+template = "doc.html"

5++++

7+This document describes the data types for Gall defined in `lull.hoon`.

9+## `bitt`

10+

11+```hoon

12++$ bitt (map duct (pair ship path))

13+```

14+

15+Incoming subscriptions.

16+

17+This is the structure Gall uses to keep track of subscribers to our Gall agent.

18+The `sup` field of a [`bowl`](#bowl) contains the `bitt` for our agent.

19+

20+## `boat`

21+

22+```hoon

23++$ boat

24+ %+ map [=wire =ship =term]

25+ [acked=? =path]

26+```

27+

28+Outgoing subscriptions.

29+

30+This is the structure Gall uses to keep track of subscriptions our agent has

31+initiated. The `wex` field of a [`bowl`](#bowl) contails the `boat` for that

32+agent.

33+

34+The `wire` field is the `wire` which [`sign:agent`](#signagent)s will come in on.

35+The `ship` and `term` fields are the ship and the name of the agent to which our

36+agent has subscribed.

37+

38+The `acked` field is `%.y` if they have acknowledged our subscription request,

39+and `%.n` if they have not. The `path` field is the `path` on the other agent to

40+which our agent has subscribed.

41+

42+## `bowl`

43+

44+```hoon

45++$ bowl :: standard app state

46+ $: $: our=ship :: host

47+ src=ship :: guest

48+ dap=term :: agent

49+ == ::

50+ $: wex=boat :: outgoing subs

51+ sup=bitt :: incoming subs

52+ == ::

53+ $: act=@ud :: change number

54+ eny=@uvJ :: entropy

55+ now=@da :: current time

56+ byk=beak :: load source

57+ == == ::

58+```

59+

60+Additional agent state.

61+

62+A `bowl` is given to the agent core each time an event comes in. The fields are

63+as follows:

64+

65+- `our`: Our ship.

66+- `src`: The ship from which the current request originated.

67+- `dap`: The name of our agent.

68+- `wex`: Outgoing subscriptions. That is, subscriptions our agent has initiated.

69+ See the [`boat`](#boat) section for details of the type.

70+- `sup`: Incoming subscriptions. That is, subscriptions others have made to our

71+ agent. See the [`bitt`](#bitt) section for details of the type.

72+- `act`: The total number of [`move`](/docs/arvo/overview#move)s our agent has

73+ processed so far.

74+- `eny`: 512 bits of entropy.

75+- `now`: The current date-time.

76+- `byk`: The ship, desk and `case` in Clay from which this agent was loaded. The

77+ `case` will be `[%da @da]` where the `@da` is the when the agent was loaded. A

78+ `beak` is a triple of `[ship desk case]`.

79+

80+## `dude`

81+

82+```hoon

83++$ dude term

84+```

85+

86+Agent name.

87+

88+## `gill`

89+

90+```hoon

91++$ gill (pair ship term)

92+```

93+

94+A general contact: A pair of the ship and agent name.

95+

96+## `scar`

97+

98+```hoon

99++$ scar

100+ $: p=@ud

101+ q=(map duct bone)

102+ r=(map bone duct)

103+ ==

104+```

105+

106+Opaque duct - used internally.

107+

108+## `suss`

109+

110+```hoon

111++$ suss (trel dude @tas @da)

112+```

113+

114+Configuration report.

115+

116+## `well`

117+

118+```hoon

119++$ well (pair desk term)

120+```

121+

122+Desk and agent.

123+

124+## `neat`

125+

126+```hoon

127++$ neat

128+ $% [%arvo =note-arvo]

129+ [%agent [=ship name=term] =deal]

130+ [%pyre =tang]

131+ ==

132+```

133+

134+Like a [`note:agent`](#noteagent), except the `%agent` case has a [`deal`](#deal) instead

135+of just a [`task:agent`](#taskagent). This is used for messages that come in over the

136+network and would not be used manually.

137+

138+## `deal`

139+

140+```hoon

141++$ deal

142+ $% [%raw-poke =mark =noun]

143+ task:agent

144+ ==

145+```

146+

147+Like a [`task:agent`](#taskagent) but with the additional case of a raw poke.

148+This is used for messages that come in over the network and would not be used

149+manually.

150+

151+## `unto`

152+

153+```hoon

154++$ unto

155+ $% [%raw-fact =mark =noun]

156+ sign:agent

157+ ==

158+```

159+

160+Like a [`sign:agent`](#signagent) but with the additional case of a raw fact.

161+This is used for messages that come in over the network and would not be used

162+manually.

163+

164+## `agent`

165+

166+```hoon

167+++ agent

168+ =< form

169+ |%

170+```

171+

172+Container for Gall agent types. The most significant arm is

173+[`form:agent`](#formagent), which specifies the structure of the agent itself.

174+There are also some additional structures defined here, mostly defining the

175+kinds of messages agents can send. The different arms of the core in `agent`

176+are considered separately below.

177+

178+### `step:agent`

179+

180+```hoon

181++$ step (quip card form)

182+```

183+

184+A cell of [`card:agent`](#cardagent)s to be sent and a new agent state. This is the

185+type returned by most arms of an agent. A `(quip a b)` is the same as `[(list a) b]`, it's just a more convenient way to specify it.

186+

187+### `card:agent`

188+

189+```hoon

190++$ card (wind note gift)

191+```

192+

193+An effect - typically a message to be sent to another agent or vane. A list of

194+these are returned by most agent arms along with a new state in a

195+[`step:agent`](#stepagent). A `wind` is the following:

196+

197+```hoon

198+++ wind

199+ |$ [a b]

200+ $% [%pass p=path q=a]

201+ [%slip p=a]

202+ [%give p=b]

203+ ==

204+```

205+

206+Gall will not allow a `%slip`, so in practice a `card` will be one of:

207+

208+- `[%pass path note]`

209+- `[%give gift]`

210+

211+For `%pass`, `p` specifies the `wire` on which a response should be returned.

212+See [`note:agent`](#noteagent) and [`gift:agent`](#giftagent) below for details of their

213+types.

214+

215+### `note:agent`

216+

217+```hoon

218++$ note

219+ $% [%agent [=ship name=term] =task]

220+ [%arvo note-arvo]

221+ [%pyre =tang]

222+ ==

223+```

224+

225+The type for messages initiated by our agent. This is opposed to

226+[`gift:agent`](#giftagent), which is the type for responding to other agents or

227+vanes, or for sending out updates to subscribers. The three cases are:

228+

229+- `%agent`: Poke another agent, subscribe to another agent, or cancel a

230+ subscription to another agent. The `ship` and `name` fields are the ship and

231+ agent to which the `task` should be sent. The `task` is the request itself,

232+ see [`task:agent`](#taskagent) below for its possible types.

233+- `%arvo`: Pass a `task` to a vane. The type of a `note-arvo` is:

234+ ```hoon

235+ +$ note-arvo

236+ $~ [%b %wake ~]

237+ $% [%a task:ames]

238+ [%b task:behn]

239+ [%c task:clay]

240+ [%d task:dill]

241+ [%e task:eyre]

242+ [%g task:gall]

243+ [%i task:iris]

244+ [%j task:jael]

245+ [%$ %whiz ~]

246+ [@tas %meta vase]

247+ ==

248+ ```

249+ You can refer to the `/sys/lull.hoon` source code for all the possible vane

250+ tasks, or see each vane's API Reference section in the [Arvo

251+ documentation](/docs/arvo/overview)

252+- `%pyre`: This is for aborting side-effects initiated during agent

253+ installation. The `tang` is an error message.

254+

255+A `note:agent` is always wrapped in a `%pass` [`card:agent`](#cardagent).

256+

257+### `task:agent`

258+

259+```hoon

260++$ task

261+ $% [%watch =path]

262+ [%watch-as =mark =path]

263+ [%leave ~]

264+ [%poke =cage]

265+ [%poke-as =mark =cage]

266+ ==

267+```

268+

269+The types of messages initiated by our agent and sent to another agent. This is

270+in contrast to [`gift:agent`](#giftagent)s, which are responses to incoming

271+messages from agents or updates to agents already subscribed. The five kinds

272+are:

273+

274+- `%watch`: Subscribe to `path` on the target ship and agent.

275+- `%watch-as`: Same as `%watch`, except you ask the target's Gall to convert

276+ subscription updates to the `mark` you specified rather than just giving you

277+ the `mark` produced by the agent.

278+- `%leave`: Cancel subscription. The particular subscription to cancel will be

279+ determined by the `wire` given in the `p` field of the containing `%pass`

280+ [`card:agent`](#cardagent).

281+- `%poke`: Poke the target ship and agent with the given `cage`, which is a pair

282+ of `[mark vase]`.

283+- `%poke-as`: Same as `%poke`, except the `cage` will be converted to the

284+ specified `mark` before sending.

285+

286+A `task:agent` is always wrapped in a `%pass` [`card:agent`](#cardagent).

287+

288+### `gift:agent`

289+

290+```hoon

291++$ gift

292+ $% [%fact paths=(list path) =cage]

293+ [%kick paths=(list path) ship=(unit ship)]

294+ [%watch-ack p=(unit tang)]

295+ [%poke-ack p=(unit tang)]

296+ ==

297+```

298+

299+The types of messages our agent can either send in response to messages from

300+other agents, or send to subscribed agents. This is in contrast to

301+[`task:agent`](#taskagent)s, which are messages to other agents our agent

302+initiates rather than sends in response. The four kinds are:

303+

304+- `%fact`: An update to existing subscribers. The `paths` field specifies which

305+ subscription paths the update should go out to. The `cage` is the data, and is

306+ a `[mark vase]`.

307+- `%kick`: Kick subscriber, ending their subscription. The `paths` field

308+ specifies which paths the subscriber should be kicked from, and the `ship`

309+ field specifies the ship to kick. If the `ship` field is null, all subscribers

310+ on the specified paths are kicked. Gall will automatically remove the

311+ subscription from our agent's [`bitt`](#bitt) (inbound subscription `map`),

312+ and subscriber will no longer receive updates on the `path`s in question.

313+- `%watch-ack`: Acknowledge a subscription request. If `p` is null, it's an ack

314+ (positive acknowledgement), and if `p` is non-null, it's a nack (negative

315+ acknowledgement). Simply crashing will caused Gall to nack a subscription

316+ request, and not crashing but not explicitly producing a `%watch-ack` `gift`

317+ will cause Gall to ack a subscription request. Therefore, you'd typically only

318+ explicitly produce a `%watch-ack` `gift` if you wanted to nack a subscription

319+ request with a custom error in the `tang`.

320+- `%poke-ack`: Acknowledge a poke. If `p` is null, it's an ack, and if `p` is

321+ non-null, it's a nack. Simply crashing will cause Gall to nack a poke, and not

322+ crashing but not explicitly producing a `%poke-ack` `gift` will cause Gall to

323+ ack a poke. Therefore, you'd typically only explicitly produce a `%poke-ack`

324+ `gift` if you wanted to nack a poke with a custom error in the `tang`.

325+

326+A `gift:agent` is always wrapped in a `%give` [`card:agent`](#cardagent).

327+

328+### `sign:agent`

329+

330+```hoon

331++$ sign

332+ $% [%poke-ack p=(unit tang)]

333+ [%watch-ack p=(unit tang)]

334+ [%fact =cage]

335+ [%kick ~]

336+ ==

337+```

338+

339+A `sign` is like a [`gift:agent`](#giftagent) but it's something that comes

340+_in_ to our agent from another agent rather than something we send out. The

341+possible types are:

342+

343+- `%poke-ack`: Another agent has acked (positively acknowledged) or nacked

344+ (negatively acknowledged) a `%poke` [`task:agent`](#taskagent) we previously

345+ sent. It's an ack if `p` is null and a nack if `p` is non-null. The `tang`

346+ contains an error or traceback if it's a nack.

347+- `%watch-ack`: Another agent has acked or nacked a `%watch`

348+ [`task:agent`](#taskagent) (subscription request) we previously sent. It's an

349+ ack if `p` is null and a nack if `p` is non-null. The `tang` contains an error

350+ or traceback if it's a nack. If it's a nack, Gall will automatically remove

351+ the subscription from our agent's [`boat`](#boat) (outbound subscription

352+ map).

353+- `%fact`: An update from another agent to which we've previously subscribed

354+ with a `%watch` [`task:agent`](#taskagent) (subscription request). The `cage`

355+ contains the data, and is a `[mark vase]`.

356+- `%kick`: Our subscription to another agent has been ended, and we'll no longer

357+ receive updates. A `%kick` may be intentional, but it may also happen due to

358+ certain network conditions or other factors. As a result, it's best to try and

359+ resubscribe with another `%watch` [`task:agent`](#taskagent), and if they

360+ nack the `%watch`, we can conclude it was intentional and give up.

361+

362+### `form:agent`

363+

364+```hoon

365+++ form

366+ $_ ^|

367+ |_ bowl

368+ ++ on-init

369+ *(quip card _^|(..on-init))

370+ ::

371+ ++ on-save

372+ *vase

373+ ::

374+ ++ on-load

375+ |~ old-state=vase

376+ *(quip card _^|(..on-init))

377+ ::

378+ ++ on-poke

379+ |~ [mark vase]

380+ *(quip card _^|(..on-init))

381+ ::

382+ ++ on-watch

383+ |~ path

384+ *(quip card _^|(..on-init))

385+ ::

386+ ++ on-leave

387+ |~ path

388+ *(quip card _^|(..on-init))

389+ ::

390+ ++ on-peek

391+ |~ path

392+ *(unit (unit cage))

393+ ::

394+ ++ on-agent

395+ |~ [wire sign]

396+ *(quip card _^|(..on-init))

397+ ::

398+ ++ on-arvo

399+ |~ [wire sign-arvo]

400+ *(quip card _^|(..on-init))

401+ ::

402+ ++ on-fail

403+ |~ [term tang]

404+ *(quip card _^|(..on-init))

405+ --

406+--

407+```

408+

409+This defines the structure of the agent itself. The agent is a door with a [`bowl`](#bowl) as its sample and exactly ten arms. Below we'll describe each arm briefly.

410+

411+#### `on-init`

412+

413+- Accepts: Nothing.

414+- Produces: [`step:agent`](#stepagent)

415+

416+This arm is called when the agent is initially installed.

417+

418+#### `on-poke`

419+

420+- Accepts: `cage`

421+- Produces: [`step:agent`](#stepagent)

422+

423+This arm is called when another agent pokes our agent.

424+

425+#### `on-watch`

426+

427+- Accepts: `path`

428+- Produces: [`step:agent`](#stepagent)

429+

430+This arm is called when another agent subscribes to our agent.

431+

432+#### `on-leave`

433+

434+- Accepts: `path`

435+- Produces: [`step:agent`](#stepagent)

436+

437+This arm is called when another agent unsubscribes from a subscription path on

438+our agent.

439+

440+#### `on-peek`

441+

442+- Accepts: `path`

443+- Produces: `(unit (unit cage))`

444+

445+This arm is called when a [scry](/docs/arvo/concepts/scry) is performed on our

446+agent.

447+

448+#### `on-agent`

449+

450+- Accepts: `[wire sign:agent]`

451+- Produces: [`step:agent`](#stepagent)

452+

453+This arm is called when another agent give our agent a

454+[`sign:agent`](#signagent).

455+

456+#### `on-arvo`

457+

458+- Accepts: `[wire sign-arvo]`

459+- Produces: [`step:agent`](#stepagent)

460+

461+This arm is called when a vane gives our agent a `gift`. A `sign-arvo` is:

462+

463+```hoon

464++$ sign-arvo

465+ $% [%ames gift:ames]

466+ $: %behn

467+ $% gift:behn

468+ $>(%wris gift:clay)

469+ $>(%writ gift:clay)

470+ $>(%mere gift:clay)

471+ $>(%unto gift:gall)

472+ ==

473+ ==

474+ [%clay gift:clay]

475+ [%dill gift:dill]

476+ [%eyre gift:eyre]

477+ [%gall gift:gall]

478+ [%iris gift:iris]

479+ [%jael gift:jael]

480+ ==

481+```

482+

483+You can refer to the `/sys/lull.hoon` source code, or the API Reference of each

484+vane in the [Arvo documentation](/docs/arvo/overview).

485+

486+#### `on-fail`

487+

488+- Accepts: `[term tang]`

489+- Produces: [`step:agent`](#stepagent)

490+

491+This arm is called if certain errors occur in Gall, such as if our agent tries

492+to create a duplicate subscription.

content/docs/userspace/gall/gall-api.md → content/docs/arvo/gall/gall-api.mdrenamed+24−24

@@ -1,6 +1,6 @@

1+++

2title = "API Reference"

3−weight = 10

3+weight = 3

4template = "doc.html"

5+++

@@ -296,7 +296,7 @@ List of cards and new agent

296

297Expose state for saving.

298

299−This arm is called immediately before the agent is upgraded. It packages the

299+This arm is called immediately before the agent is upgraded. It packages the

300permament state of the agent in a vase for the next version of the agent.

301Unlike most handlers, this cannot produce effects. It is not a gate and has no input.

302

@@ -319,7 +319,7 @@ Unlike most handlers, this cannot produce effects. It is not a gate and has no i

319

320Application upgrade.

321

322−This arm is called immediately after the agent is upgraded. It receives

322+This arm is called immediately after the agent is upgraded. It receives

323a vase of the state of the previously-running version of the agent, obtained

324from `+on-save`, which allows it to cleanly upgrade from the old agent.

325

@@ -362,7 +362,7 @@ List of cards and new agent

362

363Handle application poke.

364

365−This arm is called when the agent is "poked". The input is a cage, so

365+This arm is called when the agent is "poked". The input is a cage, so

366it's a pair of a mark and a dynamic vase.

367

368#### Accepts

@@ -445,16 +445,16 @@ List of cards and new agent.

445Handle new subscriber.

446

447This arm is called when a program wants to subscribe to the agent on a

448−particular path. The agent may or may not need to perform setup steps

448+particular path. The agent may or may not need to perform setup steps

449−to intialize the subscription. It may produce a `%give`

449+to intialize the subscription. It may produce a `%give`

450`%subscription-result` to the subscriber to get it up to date, but after

451this event is complete, it cannot give further updates to a specific

452−subscriber. It must give all further updates to all subscribers on a

452+subscriber. It must give all further updates to all subscribers on a

453specific path.

454

455If this arm crashes, then the subscription is immediately terminated.

456More specifcally, it never started -- the subscriber will receive a

457−negative `%watch-ack`. You may also produce an explicit `%kick` to

457+negative `%watch-ack`. You may also produce an explicit `%kick` to

458close the subscription without crashing -- for example, you could

459produce a single update followed by a `%kick`.

460

@@ -501,11 +501,11 @@ Handle unsubscribe.

501

502This arm is called when a program becomes unsubscribed to you.

503Subscriptions may close because the subscriber intentionally

504−unsubscribed, but they also could be closed by an intermediary. For

504+unsubscribed, but they also could be closed by an intermediary. For

505example, if a subscription is from another ship which is currently

506unreachable, Ames may choose to close the subscription to avoid queueing

507−updates indefinitely. If the program crashes while processing an

507+updates indefinitely. If the program crashes while processing an

508−update, this may also generate an unsubscription. You should consider

508+update, this may also generate an unsubscription. You should consider

509subscriptions to be closable at any time.

510

511#### Accepts

@@ -540,8 +540,8 @@ List of cards and new agent.

540Handle scry request.

541

542This arm is called when a program reads from the agent's "scry"

543−namespace, which should be referentially transparent. Unlike most

543+namespace, which should be referentially transparent. Unlike most

544−handlers, this cannot perform IO, and it cannot change the state. All

544+handlers, this cannot perform IO, and it cannot change the state. All

545it can do is produce a piece of data to the caller, or not.

546

547#### Accepts

@@ -568,8 +568,8 @@ The path being scryed for.

568```

569

570If this arm produces `[~ ~ data]`, then `data` is the value at the the

571−given path. If it produces `[~ ~]`, then there is no data at the given

571+given path. If it produces `[~ ~]`, then there is no data at the given

572−path and never will be. If it produces `~`, then we don't know yet whether

572+path and never will be. If it produces `~`, then we don't know yet whether

573there is or will be data at the given path. The head of the path is known as the

574`care`. Requests with a care of `%x` should return a vase that matches or is

575convertible to the mark at the end of the scry request. This mark is not

@@ -625,8 +625,8 @@ Handle `%pass` card

625This arm is called to handle responses to `%pass` cards to other agents.

626It will be one of the following types of response:

627

628−- `%poke-ack`: acknowledgment (positive or negative) of a poke. If the

628+- `%poke-ack`: acknowledgment (positive or negative) of a poke. If the

629− value is `~`, then the poke succeeded. If the value is `[~ tang]`,

629+ value is `~`, then the poke succeeded. If the value is `[~ tang]`,

630 then the poke failed, and a printable explanation (eg a stack trace)

631 is given in the `tang`.

632

@@ -716,7 +716,7 @@ This arm is called to handle responses for `%pass` cards to vanes.

716`wire` is the wire from the `++gift` that triggered `++on-arvo`.

717

718`sign` is the response from the vane. The list of possible responses from the

719−vanes is statically defined in sys/zuse.hoon (grep for `++ sign-arvo`).

719+vanes is statically defined in sys/zuse.hoon (grep for `++ sign-arvo`).

720

721#### Returns

722

@@ -761,9 +761,9 @@ List of cards and new agent.

761Handle error.

762

763If an error happens in `+on-poke`, the crash report goes into the

764−`%poke-ack` response. Similarly, if an error happens in

764+`%poke-ack` response. Similarly, if an error happens in

765`+on-subscription`, the crash report goes into the `%watch-ack`

766−response. If a crash happens in any of the other handlers, the report

766+response. If a crash happens in any of the other handlers, the report

767is passed into this arm.

768

769#### Accepts

@@ -821,9 +821,9 @@ subscription content for all subscribers on a given path.

821```

822

823`(list path)` is a list of the paths to send the update on. If no path is

824− given, then the update is only given to the program that instigated the

824+given, then the update is only given to the program that instigated the

825− request. Typical use of this mode is in `+on-watch` to give an initial update

825+request. Typical use of this mode is in `+on-watch` to give an initial update

826− to a new subscriber to get them up to date.

826+to a new subscriber to get them up to date.

827

828`cage` is a cage of the subscription update.

829

@@ -938,7 +938,7 @@ This note is given to subscribe to an application at a path

938

939Unsubscribe from an application.

940

941− This note is passed to unsubscribe from an application. It should be passed on

941+This note is passed to unsubscribe from an application. It should be passed on

942the same wire that the corresponding `%watch` note for the subscription was

943passed on.

944

content/docs/userspace/gall/gall.md → content/docs/arvo/gall/gall.mdrenamed

The content is the same.

content/docs/arvo/gall/overview.mddeleted−11

@@ -1,11 +0,0 @@

1−+++

2−title = "Overview"

3−weight = 1

4−template = "doc.html"

5−+++

6−

7−**Gall** is the application-management [vane](/docs/glossary/vane). Userspace apps –⁠ daemons, really –⁠ are started, stopped, and sandboxed by Gall. Gall provides developers with a consistent interface for connecting their app to [Arvo](/docs/arvo/arvo). It allows applications and other vanes to send messages to applications and subscribe to data streams. Messages coming into Gall are routed to the intended application, and the response comes back along the same route. If the intended target is on another [ship](/docs/glossary/ship), Gall will route it behind the scenes through [Ames](/docs/arvo/ames/ames) to the other ship.

8−

9−Gall is located at `/home/sys/vane/gall.hoon` within Arvo.

10−

11−For more details, see the [userspace](/docs/userspace/gall/gall) section.

content/docs/arvo/overview.md+1−1

@@ -543,7 +543,7 @@ As of this writing, we have nine vanes, which each provide the following service

543- [Eyre](/docs/arvo/eyre/eyre): an http server. Unix sends http messages to `%eyre`, and `%eyre` produces http messages in response.

544- [Ford](/docs/arvo/ford/ford): a build system also utilized for marks

545 (file types) and debugging.

546−- [Gall](/docs/userspace/gall/gall): manages our userspace applications. `%gall` keeps state and manages subscribers.

546+- [Gall](/docs/arvo/gall/gall): manages our userspace applications. `%gall` keeps state and manages subscribers.

547- [Iris](/docs/arvo/iris/iris): an http client.

548- [Jael](/docs/arvo/jael/jael): storage for Azimuth information.

549

content/docs/arvo/reference/filesystem.md+1−1

@@ -13,7 +13,7 @@ is not perfectly adhered to - sometimes you may find structure definitions in

13`/lib`, for example.

15- `/app` contains userspace applications, i.e. [Gall

16− agents](/docs/userspace/gall/gall).

16+ agents](/docs/arvo/gall/gall).

17- `/gen` contains generators. Many applications make use of generators, but also

18 each generator in this folder may be run from dojo using `+`. For example,

19 `/gen/foo/hoon` in the `%base` desk is run with `+foo`. Generators on desks

content/docs/development/develop.md+4−4

@@ -13,7 +13,7 @@ contribute to. At a high level, you can:

13- [Build clients](#clients), which use Urbit as their back-end to store data and

14 interact with the network

15- [Develop agents](#agents), or more precisely [_gall_

16− agents](/docs/userspace/gall/gall), which are written in [Hoon](/docs/hoon/)

16+ agents](/docs/arvo/gall/gall), which are written in [Hoon](/docs/hoon/)

17 and can best be thought of as microservices

18- [Contribute to Urbit's core](#core), which involves contributing to Urbit

19 itself — either the operating system

@@ -60,8 +60,8 @@ library called `shoe`, which you can learn more about

60Gall agents can be best thought of as individual services with a

61statically-typed interface and built-in database. They're written in

62[Hoon](/docs/hoon/overview) and all conform to a specific

63−[interface](/docs/userspace/gall/gall-api) that's defined by the kernel vane

63+[interface](/docs/arvo/gall/gall-api) that's defined by the kernel vane

64−called [Gall](/docs/userspace/gall/gall).

64+called [Gall](/docs/arvo/gall/gall).

66Applications built on Urbit utilize a collection of different agents, each of

67which handle specific functionality. The [Landscape

@@ -70,7 +70,7 @@ to see how this pattern works in practice.

71If you want to learn how to build gall agents, your best bet is to first [learn

72the Hoon programming language](/docs/hoon/hoon-school/), and then follow that

73−up with the [Gall guide](/docs/userspace/gall/tutorial).

73+up with the [Gall guide](/docs/userspace/gall-guide).

75### Contribute to Urbit Core {#core}

content/docs/glossary/aqua.md−4

@@ -10,7 +10,3 @@ category = "arvo"

10Aqua is a [Gall](/docs/glossary/gall) app that runs an [Arvo](/docs/glossary/arvo) instance or instances in userspace. It pretends to be [Vere](/docs/glossary/vere), and as such it loads [Pills](/docs/glossary/pill) to boot up a virtual ship or fleet of ships and then manages them from within the parent Arvo instance. Running tests for a virtual fleet of Aqua ships is done using [pH](/docs/glossary/ph).

12Aqua is jetted with the usual [Nock](/docs/glossary/nock) interpreter and thus virtual ships do not run any slower than the parent ship.

13−

14−### Further Reading

15−

16−- [The Gall tutorial](/docs/userspace/gall/gall): A technical guide to the Gall vane.

content/docs/glossary/gall.md+2−1

@@ -14,4 +14,5 @@ Gall is located at `/home/sys/vane/gall.hoon` within Arvo.

15- [The Hoon Tutorial](/docs/hoon/hoon-school/): Our guide to learning the Hoon programming language that will give you the foundation necessary for app development.

16 - [Lesson 2.7: Gall](/docs/hoon/hoon-school/gall): A Hoon Tutorial lesson that explains how to write a simple Gall app.

17+- [Gall vane documentation](/docs/arvo/gall/gall): Documentation of the Gall vane.

17−- [The Gall tutorial](/docs/userspace/gall/gall): A technical guide to the Gall vane.

18+- [Gall Guide](/docs/userspace/gall-guide): A tutorial for writing Gall agents.

content/docs/system-overview/arvo.md+1−1

@@ -27,6 +27,6 @@ Arvo modules are also called 'vanes'. Arvo's vanes are:

27 Also includes our typed functional build system.

28- [Dill](/docs/arvo/dill/dill): terminal driver.

29- [Eyre](/docs/arvo/eyre/eyre): HTTP server.

30−- [Gall](/docs/userspace/gall/gall): application sandbox and manager.

30+- [Gall](/docs/arvo/gall/gall): application sandbox and manager.

31- [Iris](/docs/arvo/iris/iris-api): HTTP client.

32- [Jael](/docs/arvo/jael/jael-api): Public and private key storage.

content/docs/userspace/_index.md+2−2

@@ -12,9 +12,9 @@ Urbit's userspace is managed by Arvo's Gall vane.

13An overview of userspace in Urbit.

15−## [Gall](/docs/userspace/gall/gall)

15+## [Gall Guide](/docs/userspace/gall-guide)

17−Resources on Gall which manages userspace applications.

17+Learn how to develop Gall agents.

19## [Landscape](/docs/userspace/landscape/)

content/docs/userspace/gall/tutorial.md → content/docs/userspace/gall-guide.mdrenamed+1−1

@@ -1,5 +1,5 @@

1+++

2−title = "Tutorial"

2+title = "Gall Guide"

3weight = 5

4template = "doc.html"

5+++

content/docs/userspace/gall/_index.mddeleted−21

@@ -1,21 +0,0 @@

1−+++

2−title = "Gall"

3−weight = 40

4−sort_by = "weight"

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

6−insert_anchor_links = "right"

7−+++

8−

9−Gall is the Arvo vane that manages userspace applications.

10−

11−## [Overview](/docs/userspace/gall/gall)

12−

13−Overview of the Gall vane.

14−

15−## [Tutorial](/docs/userspace/gall/tutorial)

16−

17−Tutorial for writing Gall agents.

18−

19−## [API Reference](/docs/userspace/gall/gall-api)

20−

21−Reference information.

content/docs/userspace/landscape/overview.md+5−14

@@ -16,7 +16,6 @@ As of this year, this application suite has arrived at a point where we’re

16confident both in how all the parts fit together, and confident in the

17individual parts.

19−

20## What is Landscape Intended to Be?

19## What is Landscape Intended to Be?

22Landscape is a single suite of userspace applications built to run on top of

21Landscape is a single suite of userspace applications built to run on top of

@@ -28,16 +27,14 @@ making Landscape itself more extensible for user-developers in late 2021.

28Landscape is specifically a social suite of applications, meant to enable

27Landscape is specifically a social suite of applications, meant to enable

29communication and socializing in many forms.

28communication and socializing in many forms.

31−

32## What is Landscape technically composed of?

30## What is Landscape technically composed of?

34Landscape is composed of two primary parts: its backend, which runs as a suite of userspace applications (also known as Gall agents), and its frontend interface, which runs as a single-page web application. Both the backend and the frontend may be decomposed into their constituent parts for further understanding.

32Landscape is composed of two primary parts: its backend, which runs as a suite of userspace applications (also known as Gall agents), and its frontend interface, which runs as a single-page web application. Both the backend and the frontend may be decomposed into their constituent parts for further understanding.

36−

37### Backend

34### Backend

39The Landscape backend is implemented as a collection of long-running

36The Landscape backend is implemented as a collection of long-running

40−microservices known as [Gall agents](/docs/userspace/gall/gall). They can be divided into the following,

37+microservices known as [Gall agents](/docs/arvo/gall/gall). They can be divided into the following,

41though this is a simplification:

38though this is a simplification:

43- **Graph**: handles storing messages / posts in a non-relational database

40- **Graph**: handles storing messages / posts in a non-relational database

@@ -55,7 +52,6 @@ two main categories: [stores](#stores) and [hooks](#hooks). To simply describe

55the separation of responsibilities, stores are dumb databases (models in MVC)

52the separation of responsibilities, stores are dumb databases (models in MVC)

56and hooks are for processing data (controllers in MVC).

53and hooks are for processing data (controllers in MVC).

58−

59### Stores {#stores}

55### Stores {#stores}

61Concisely defined, a store is a dumb database. It does not send outgoing pokes,

57Concisely defined, a store is a dumb database. It does not send outgoing pokes,

@@ -71,11 +67,10 @@ modules. Examples include:

71and

67and

72[invite-store](https://github.com/urbit/urbit/blob/ac096d85ae847fcfe8786b51039c92c69abc006e/pkg/arvo/app/invite-store.hoon).

68[invite-store](https://github.com/urbit/urbit/blob/ac096d85ae847fcfe8786b51039c92c69abc006e/pkg/arvo/app/invite-store.hoon).

74−

75### Hooks {#hooks}

70### Hooks {#hooks}

77A hook is a more loosely-defined agent that performs business logic. It should

72A hook is a more loosely-defined agent that performs business logic. It should

78−only keep track of a minimal amount of state (*e.g.* active subscriptions). Hooks

73+only keep track of a minimal amount of state (_e.g._ active subscriptions). Hooks

79are used for a variety of purposes in the system, but there are a few important

74are used for a variety of purposes in the system, but there are a few important

80hook patterns to be aware of:

75hook patterns to be aware of:

@@ -106,7 +101,6 @@ received.

106The poke-proxy-hook conditionally forwards a poke from a foreign ship to a store

101The poke-proxy-hook conditionally forwards a poke from a foreign ship to a store

107on the local ship if the foreign ship has permission to do so.

102on the local ship if the foreign ship has permission to do so.

108

103

109−

110### Major Components

104### Major Components

111

105

112#### Groups

106#### Groups

@@ -170,24 +164,21 @@ be thought of as a database join between the `%group-store` and the

170`%graph-store`, as it provides bidirectional indices for querying all of the

164`%graph-store`, as it provides bidirectional indices for querying all of the

171graphs that a group has, or which group a particular graph is associated with.

165graphs that a group has, or which group a particular graph is associated with.

172

166

173−

174#### Contacts

167#### Contacts

175

168

176Contacts are your address book. Individual ships (people) you talk to may have a

169Contacts are your address book. Individual ships (people) you talk to may have a

177− nickname, a profile picture, or a colored sigil background that helps you

170+nickname, a profile picture, or a colored sigil background that helps you

178− identify them in groups, chatrooms, blogs, and collections.

171+identify them in groups, chatrooms, blogs, and collections.

179−

180

172

181#### Invites

173#### Invites

182

174

183Invites is a simple subsystem that allows you to send all the details of a given

175Invites is a simple subsystem that allows you to send all the details of a given

184−resource (*e.g.* graph or group) to some other ship so that they may join it if

176+resource (_e.g._ graph or group) to some other ship so that they may join it if

185they desire to. Invite acceptance is handled with threads that listen to the

177they desire to. Invite acceptance is handled with threads that listen to the

186`%invite-store` using the `%observe-hook` and invite sending is handled with the

178`%invite-store` using the `%observe-hook` and invite sending is handled with the

187`%invite-hook`, which allows any ship to send you an invite without any

179`%invite-hook`, which allows any ship to send you an invite without any

188permissions involved.

180permissions involved.

189

181

190−

191#### Hark

182#### Hark

192

183

193Hark is a generic notification and unread-tracking subsystem that currently

184Hark is a generic notification and unread-tracking subsystem that currently

content/docs/userspace/overview.md+2−2

@@ -6,9 +6,9 @@ template = "doc.html"

7Urbit's userspace is managed by Arvo's Gall vane.

9−## [Gall](/docs/userspace/gall/gall)

9+## [Gall Guide](/docs/userspace/gall-guide)

11−Resources on Gall which manages userspace applications.

11+Learn how to develop Gall agents.

13## [Graph Store](/docs/userspace/graph-store)

content/docs/userspace/threads/overview.md+13−12

@@ -4,27 +4,26 @@ weight = 1

4template = "doc.html"

5+++

7−As discussed in the [Gall](/docs/userspace/gall/gall) section, Urbit code lives in the following basic

7+Urbit code lives in the following basic categories:

8−categories:

10- Runtime (Nock interpreter, persistence engine, IO drivers, jets)

9- Runtime (Nock interpreter, persistence engine, IO drivers, jets)

11- Kernel vanes (managed by Arvo)

10- Kernel vanes (managed by Arvo)

12- Userspace agents (managed by Gall, permanent state)

11- Userspace agents (managed by Gall, permanent state)

13- Userspace threads (managed by Spider, transient state)

12- Userspace threads (managed by Spider, transient state)

15−This describes the last category: Threads.

14+This describes the last category: Threads.

17A thread is a monadic function that takes arguments and produces a

16A thread is a monadic function that takes arguments and produces a

18−result. It may perform input and output while running, so it is not a

17+result. It may perform input and output while running, so it is not a

19−pure function. It may fail.

18+pure function. It may fail.

21−An agent's strength is that it's permanent and bulletproof. All state

20+An agent's strength is that it's permanent and bulletproof. All state

22transitions are defined, and each action it performs is a transaction.

21transitions are defined, and each action it performs is a transaction.

23Code upgrades preserve existing state.

22Code upgrades preserve existing state.

25−An agent's weakness is complex input and output. Since each state

24+An agent's weakness is complex input and output. Since each state

26transition must be explicitly handled, the complexity of an agent

25transition must be explicitly handled, the complexity of an agent

27−explodes with the amount of IO it handles. At best, this results in

26+explodes with the amount of IO it handles. At best, this results in

28long and complex code; at worst, unexpected states are mishandled,

27long and complex code; at worst, unexpected states are mishandled,

29corrupting permanent state.

28corrupting permanent state.

@@ -35,17 +34,17 @@ provide a natural framework for IO.

35A thread's weakness is that it's impermanent and may fail unexpectedly.

34A thread's weakness is that it's impermanent and may fail unexpectedly.

36In most of its intermediate states, it expects only a small number of

35In most of its intermediate states, it expects only a small number of

37events (usually one), so if it receives anything it didn't expect, it

36events (usually one), so if it receives anything it didn't expect, it

38−fails. When code is upgraded, it's impossible to upgrade a running

37+fails. When code is upgraded, it's impossible to upgrade a running

39thread, so it fails.

38thread, so it fails.

41−Thus, for anything that needs to be permament, use an agent. When you

40+Thus, for anything that needs to be permament, use an agent. When you

42need to do a long or complex sequence of IO operations, reduce that to a

41need to do a long or complex sequence of IO operations, reduce that to a

43−single logical IO operation by spinning it out into a thread. If you

42+single logical IO operation by spinning it out into a thread. If you

44only change your agent's state in response to success of the thread, an

43only change your agent's state in response to success of the thread, an

45IO failure will never result in partially applied state changes.

44IO failure will never result in partially applied state changes.

47A thread may also be run from the dojo by prefixing its name with `-`

46A thread may also be run from the dojo by prefixing its name with `-`

48−and giving it any arguments it requires. If alone, any result will be

47+and giving it any arguments it requires. If alone, any result will be

49printed to the screen; else the output may be piped into an agent or

48printed to the screen; else the output may be piped into an agent or

50other sinks.

49other sinks.

@@ -60,6 +59,7 @@ These docs walk through the fundamental things you need to know to write threads

605. [Summary](/docs/userspace/threads/basics/summary)

595. [Summary](/docs/userspace/threads/basics/summary)

62## Gall

61## Gall

62+

63These docs walk through the basics of interacting with threads from gall agents.

651. [Start a thread](/docs/userspace/threads/gall/start-thread)

@@ -78,4 +78,5 @@ These docs walk through the basics of interacting with threads from gall agents.

78- [Take a fact](/docs/userspace/threads/examples/take-fact) - Subscribe to an agent and receive a fact.

80## [Reference](/docs/userspace/threads/reference)

81+

81Basic reference information. For usage of particular `strandio` functions just refer directly to `/lib/strandio/hoon` since they're largely self-explanatory.

82Basic reference information. For usage of particular `strandio` functions just refer directly to `/lib/strandio/hoon` since they're largely self-explanatory.