@@ -9,13 +9,14 @@ Hall's implementation is structured according to the new Gall model. Familiarity
99
1010* [Introduction](#introduction)
1111* [Structures & functionality](#structures--functionality)
12− * [Partners](#partners)
12+ * [Circles](#circles)
1313 * [Messages](#messages)
1414 * [Participant metadata](#participant-metadata)
1515 * [Configurations](#configurations)
1616 * [Stories](#stories)
1717 * [General use](#general-use)
1818 * [Federation](#federation)
19+ * [Public membership](#public-membership)
1920* [Interfaces for applications](#interfaces-for-applications)
2021 * [Interactions](#interactions)
2122 * [Queries, prizes and rumors](#queries-prizes-and-rumors)
@@ -36,25 +37,18 @@ Hall's implementation is structured according to the new Gall model. Familiarity
3637
3738Talk was Urbit's first big user-facing application. It continues to enjoy a prominent role in the Urbit landscape, but does so as two separate applications this time.
3839
39−The messaging parts of talk have been separated from its user interface parts. What we ended up with is a shiny new generic messaging bus, and the chat interface we all know and love. The messaging bus, which should now prove useful to many different applications, will be named `Hall`. Applications that use it are referred to as Hall *readers*. One such application, as you might have guessed, is `Talk`.
40+The messaging parts of Talk have been separated from its user interface parts. What we ended up with is a shiny new generic messaging bus, and the chat interface we all know and love. The messaging bus, which should now prove useful to many different applications, will be named `Hall`. Applications that use it are referred to as *clients*. One such application, as you might have guessed, is `Talk`.
4041
4142
4243## Structures & functionality
4344
44−### Partners
45−
46−One of Hall's strengths is that it can not only interface with other Hall instances (Halls, if you will), but also external services. We define a single structure that can be used to specify both kinds of messaging targets.
45+### Circles
4746
4847```
49−++ partner (each circle passport) :< message target
50−++ circle {hos/ship nom/knot} :< native target
51−++ passport :> foreign target
52− $% {$twitter p/cord} :< twitter handle
53− == ::
48+++ circle {hos/ship nom/term} :< native target
5449```
5550
56−A `partner` is either a `circle` or a `passport`. A `circle` is a native partner, essentially a named collection of messages created by and hosted on a ship's Hall, usually represented as `~ship-name/circle-name`.
57−A `passport` is a non-native partner, such as a Twitter feed. The possibilities for passports are endless... but none of them are properly implemented yet. For the rest of this document we'll assume a `partner` is always a `circle`.
51+A `circle` is essentially a named collection of messages created by and hosted on a ship's Hall, usually represented as `~ship-name/circle-name`. Most of Hall revolves around doing things with circles.
5852
5953### Messages
6054
@@ -63,46 +57,36 @@ When we subscribe to a circle, the primary thing we're interested in is its mess
6357```
6458++ speech :> content body
6559 $% {$lin pat/? msg/cord} :< no/@ text line
66− {$ire tos/serial sep/speech} :< in-reply-to
67− {$url url/purf} :< parsed url
68− {$app app/term msg/cord} :< app message
69− {$ext nom/term dat/*} :< extended action
70− :: ... ::
60+ {$url url/purf:eyre} :< parsed url
61+ {$exp exp/cord res/(list tank)} :< hoon line
62+ {$ire top/serial sep/speech} :< in reply to
63+ {$fat tac/attache sep/speech} :< attachment
64+ {$app app/term sep/speech} :< app message
65+ {$inv inv/? cir/circle} :< inv/ban for circle
7166 == ::
7267```
7368
74−At the heart of every message lies a `speech` that describes the message body. There's a large number of different speech types, from simple text messages to parsed URLs, Hoon expressions and more. Thought the system strives to eventually accommodate all use cases, the `%ext` speech type provides extensibility for applications that feel their needs aren't covered.
75−
76−```
77−++ statement {wen/@da boq/bouquet sep/speech} :< when what body
78−++ bouquet (set flavor) :< complete aroma
79−++ flavor path :< content flavor
80−```
81−
82−Message bodies are wrapped in a `statement` which specifies the timestamp and `flavor` of its content, the latter of which can in the future be used to filter out the kinds of content you personally do not wish to see.
69+At the heart of every message lies a `speech` that describes the message body. There's a large number of different speech types, from simple text messages to parsed URLs, Hoon expressions and more.
8370
8471```
85−++ audience (map partner (pair envelope delivery)) :< destination + state
86−++ envelope {vis/? sen/(unit partner)} :< visible sender
87−++ delivery :> delivery state
88− $? $pending :< undelivered
89− $received :< delivered
90− $rejected :< undeliverable
91− $released :< sent one-way
92− $accepted :< fully processed
72+++ audience (set circle) :< destinations
73+++ serial @uvH :< unique identifier
74+++ thought :> inner message
75+ $: uid/serial :< unique identifier
76+ aud/audience :< destinations
77+ wen/@da :< timestamp
78+ sep/speech :< content
9379 == ::
9480```
9581
96−When specifying a message's destination, an `audience` is used. It contains all the recipients of the message, as well as the delivery state for each of those recipients.
82+A `speech` is always accompanied by various bits of metadata. We include a unique identifier, a message timestamp and an `audience`, the set of all intended recipients of the message.
9783
9884```
99−++ telegram {aut/ship tot/thought} :< who thought
100−++ thought {uid/serial aud/audience sam/statement} :< which whom this
101−++ serial @uvH :< unique identifier
85+++ telegram {aut/ship thought} :< whose message
86+++ envelope {num/@ud gam/telegram} :< outward message
10287```
10388
104−The message and its destination get put into a `thought`, which also carries a universally unique identifier. This way, recipients can easily check whether they're receiving a new message or a potentially modified version of an existing one.
105−Finally, all this gets put into a `telegram` which tags it with the message's author.
89+Finally, before sending the message over the wire, we add on the message's original author. In most cases, we also include a sequence number, the index of the message in the originating circle's list of messages. This can be a useful point of reference for clients.
10690
10791### Participant metadata
10892
@@ -119,20 +103,21 @@ Messages aren't the only thing a subscription gets us. We're also kept up to dat
119103 $talk :< typing
120104 == ::
121105++ human :> human identifier
122− $: tru/(unit (trel cord (unit cord) cord)) :< true name
123− han/(unit cord) :< handle
106+ $: han/(unit cord) :< handle
107+ tru/(unit truename) :< true name
124108 == ::
109+++ truename {fir/cord mid/(unit cord) las/cord} :< real-life name
125110```
126111
127112`status` is user-set metadata that describes, well, the status of users in a circle. This encompasses their `presence`, which shows their activity, and their `human` identity, which includes their display handle.
128−For reasons we'll discover shortly, circles keep track of both their own `group` and those of the partners they're subscribed to. `crowd` encapsulates this.
113+For reasons we'll discover shortly, circles keep track of both their own `group` and those of the circles they're subscribed to. `crowd` encapsulates this.
129114
130115### Configurations
131116
132117```
133118++ lobby {loc/config rem/(map circle config)} :< our & srcs configs
134119++ config :> circle config
135− $: src/(set partner) :< active sources
120+ $: src/(set circle) :< active sources
136121 cap/cord :< description
137122 fit/filter :< message rules
138123 con/control :< restrictions
@@ -154,10 +139,10 @@ Lastly, there's a `control` structure that contains both a security mode and a l
154139
155140```
156141++ security :> security mode
157− $? $black :< channel, blacklist
158− $white :< village, whitelist
159− $green :< journal, author list
160− $brown :< mailbox, our r, bl w
142+ $? $channel :< blacklist
143+ $village :< whitelist
144+ $journal :< pub r, whitelist w
145+ $mailbox :< our r, blacklist w
161146 == ::
162147```
163148
@@ -172,13 +157,13 @@ To see how that all ties together, we're going to take a look at Hall's state.
172157
173158```
174159++ state :> hall state
175− $: stories/(map knot story) :< conversations
160+ $: stories/(map term story) :< conversations
176161 :: ... ::
177162 == ::
178163++ story :> wire content
179164 $: grams/(list telegram) :< all messages
180165 locals/group :< local presence
181− remotes/(map partner group) :< remote presence
166+ remotes/(map circle group) :< remote presence
182167 shape/config :< configuration
183168 mirrors/(map circle config) :< remote config
184169 :: ... ::
@@ -191,23 +176,27 @@ With the configuration described above in mind, we can try and imagine the thing
191176
192177### General use
193178
194−Upon initial startup, Hall creates a default story, a mailbox named `porch`. (This name is different for stars and galaxies: `floor` and `court` respectively.) This mailbox is the primary target for anyone and anything that wants to reach its owner. Applications can use it to send notifications and other information to the user (Hall itself does this as well), and users can use it to direct-message others.
179+Upon initial startup, Hall creates a default story, a mailbox named `inbox`. This mailbox is the primary target for anyone and anything that wants to reach its owner. Applications can use it to send notifications and other information to the user (Hall itself does this as well), and users can use it to send direct messages to each other.
195180
196−Applications that use Hall are encouraged to use the default mailbox as the primary messaging hub. This way, users can easily switch between different applications without "losing" their subscriptions, message backlog, etc.
181+Applications that use Hall, especially clients, are encouraged to use the default mailbox as the primary messaging hub. This way, users can easily switch between different applications without "losing" their subscriptions, message backlog, etc.
197182
198−As an example, Talk operates like this, serving as an interface for reading from and managing the user's mailbox. Local stories are subscribed to through the `porch`, which ends up containing all messages the user receives.
183+As an example, Talk operates like this, serving as an interface for reading from and managing the user's mailbox. Local stories are subscribed to through the `inbox`, which ends up containing all messages the user receives.
199184
200185### Federation
201186
202187Some places, like `urbit-meta`, will want to be easily accessible to everyone on the network, and actually support the load that comes with that. Both these desired can be met through federation.
203188
204189In federation, stories and any changes to them trickle down from ~zod, to other galaxies, to their stars. Only changes to messages and presence can also move upstream, from stars, to galaxies, to ~zod (and then back down again).
205−This way, all planets and comets will be able to subscribe to `/urbit-meta` and get all updates on the story, regardless of where on the network they originated.
190+This way, all planets and comets will be able to subscribe to `/urbit-meta` (that is, the `urbit-meta` circle on their parent ship) and get all updates on the story, regardless of where on the network they originated.
191+
192+### Public membership
193+
194+To aid in discoverability of circles, it is possible for users to make their participation in any given circle public. This data can then be used by things like profile widgets, or read out directly by other users.
206195
207196
208197## Interfaces for applications
209198
210−Applications can interact with Hall in two complementary ways: they can tell it what actions to perform, and they can subscribe to its state changes.
199+Applications can interact with Hall in two complementary ways: they can tell it what actions to perform, and they can subscribe to its state and the changes made to it.
211200
212201### Interactions
213202
@@ -216,21 +205,23 @@ Hall can be commanded by poking it with `action`s.
216205```
217206++ action :> user action
218207 $% :: circle configuration ::
219− {$create nom/knot des/cord sec/security} :< create circle
220− {$delete nom/knot why/(unit cord)} :< delete + announce
221− {$depict nom/knot des/cord} :< change description
222− {$filter nom/knot fit/filter} :< change message rules
223− {$permit nom/knot inv/? sis/(set ship)} :< invite/banish
224− {$source nom/knot sub/? src/(set partner)} :< un/sub to/from src
208+ {$create nom/term des/cord sec/security} :< create circle
209+ {$delete nom/term why/(unit cord)} :< delete + announce
210+ {$depict nom/term des/cord} :< change description
211+ {$filter nom/term fit/filter} :< change message rules
212+ {$permit nom/term inv/? sis/(set ship)} :< invite/banish
213+ {$source nom/term sub/? srs/(set source)} :< un/sub to/from src
225214 :: messaging ::
226215 {$convey tos/(list thought)} :< post exact
227− {$phrase aud/(set partner) ses/(list speech)} :< post easy
216+ {$phrase aud/audience ses/(list speech)} :< post easy
228217 :: personal metadata ::
229− {$notify nos/(set knot) pes/presence} :< our presence update
230− {$naming nos/(set knot) man/human} :< our name update
218+ {$notify aud/audience pes/(unit presence)} :< our presence update
219+ {$naming aud/audience man/human} :< our name update
231220 :: changing shared ui ::
232− {$human sip/ship man/human} :< new identity
233− {$glyph gyf/char pas/(set partner) bin/?} :< un/bind a glyph
221+ {$glyph gyf/char aud/audience bin/?} :< un/bind a glyph
222+ {$nick who/ship nic/cord} :< new identity
223+ :: misc changes ::
224+ {$public add/? cir/circle} :< show/hide membership
234225 == ::
235226```
236227
@@ -242,32 +233,38 @@ To send messages, two interfaces are available. `%convey` lets you specify all d
242233
243234"Shared UI" encompasses UI data that should be consistent across applications. For example, if the user sets a local nickname for an identity, they expect to see that nickname regardless of the application they're currently using. The same goes for glyph bindings, for easy audience targeting.
244235
245−Sometimes, in response to a user action, Hall will respond with a `reaction`.
246−
247−```
248−++ reaction :> user information
249− $: res/?($info $fail) :< result
250− wat/cord :< explain
251− why/(unit action) :< cause
252− == ::
253−```
254−
255−These are used to inform the application (and thus the user) of any unexpected side effects or errors that occurred as a result of the action they issued.
256−
257236### Queries, prizes and rumors
258237
259−To receive data from Hall, applications will have to query it. There are two paths that are useful for readers to query. Let's look at them and their results.
238+To receive data from Hall, applications will have to query it. There are two paths that are useful for clients to query. Let's look at them and their results.
260239
261240```
262241++ query :> query paths
263− $% {$reader $~} :< shared ui state
264− {$circle nom/knot ran/range} :< story query
242+ $% {$client $~} :< shared ui state
243+ $: $circle :> story query
244+ nom/naem :< circle name
245+ wat/(set circle-data) :< data to get
246+ ran/range :< query duration
247+ == ::
265248 :: ... ::
266249 == ::
267−++ range (unit {hed/place tal/(unit place)}) :< msg range, @ud/@da
268−++ place $%({$da @da} {$ud @ud}) :< point for range
250+++ circle-data :> kinds of circle data
251+ $? $grams :< messages
252+ $group-l :< local presence
253+ $group-r :< remote presences
254+ $config-l :< local config
255+ $config-r :< remote configs
256+ == ::
257+++ range :> inclusive msg range
258+ %- unit :< ~ means everything
259+ $: hed/place :< start of range
260+ tal/(unit place) :< opt end of range
261+ == ::
262+++ place :> range indicators
263+ $% {$da @da} :< date
264+ {$ud @ud} :< message number
265+ == ::
269266++ prize :> query result
270− $% $: $reader :< /reader
267+ $% $: $client :< /client
271268 gys/(jug char (set partner)) :< glyph bindings
272269 nis/(map ship cord) :< nicknames
273270 == ::
@@ -281,37 +278,38 @@ To receive data from Hall, applications will have to query it. There are two pat
281278 == ::
282279```
283280
284−To be clear, the paths for those queries are `/reader` and `/circle/[name]/[start]/[end]`, where `start` and `end` are optional and can be either a date or a message number.
285−`/reader` queries produce shared UI state. That is, glyph bindings and nicknames.
281+To be clear, the paths for those queries are `/client` and `/circle/[name]/[data]/[start]/[end]`, where data is at least one `circle-data`, and `start` and `end` are optional and can be either a date or a message number.
282+`/client` queries produce shared UI state. That is, glyph bindings and nicknames.
286283`/circle` queries produce the entire public state of the requested story, including remotes.
287284
288285Any changes to the results of these queries are communicated via the following `rumor`s. It's a fairly long list of potential changes,
289286
290287```
291288++ rumor :< query result change
292− $% $: $reader :< /reader
293− $= dif ::
294− $% {$glyph diff-glyph} ::
295− {$nick diff-nick} ::
296− == ::
297− == ::
298− {$circle dif/diff-story} :< /circle
289+ $% {$client rum/rumor-client} :< /client
290+ {$circle rum/rumor-story} :< /circle
299291 :: ... ::
300292 == ::
301−++ diff-glyph {bin/? gyf/char pas/(set partner)} :< un/bound glyph
293+++ rumor-client :< changed ui state
294+ $% {$glyph diff-glyph} :< un/bound glyph
295+ {$nick diff-nick} :< changed nickname
296+ == ::
297+++ diff-glyph {bin/? gyf/char aud/audience} :< un/bound glyph
302298++ diff-nick {who/ship nic/cord} :< changed nickname
303−++ diff-story ::
299+++ diff-story :> story change
304300 $% {$new cof/config} :< new story
305− {$grams gaz/(list telegram)} :< new/changed msgs
306301 {$config cir/circle dif/diff-config} :< new/changed config
307− {$status pan/partner who/ship dif/diff-status} :< new/changed status
308− {$follow sub/? pas/(set partner)} :< un/subscribe
302+ {$status cir/circle who/ship dif/diff-status} :< new/changed status
309303 {$remove $~} :< removed story
310304 :: ... ::
311305 == ::
306+++ rumor-story ::> story rumor
307+ $? diff-story ::< both in & outward
308+ $% {$gram nev/envelope} ::< new/changed msgs
309+ == == ::
312310++ diff-config :> config change
313311 $% {$full cof/config} :< set w/o side-effects
314− {$source add/? pas/(set partner)} :< add/rem sources
312+ {$source add/? src/source} :< add/rem sources
315313 {$caption cap/cord} :< changed description
316314 {$filter fit/filter} :< changed filter
317315 {$secure sec/security} :< changed security
@@ -322,16 +320,16 @@ Any changes to the results of these queries are communicated via the following `
322320 $% {$full sat/status} :< fully changed status
323321 {$presence pec/presence} :< changed presence
324322 {$human dif/diff-human} :< changed name
325− {$remove $~} :< removed config
323+ {$remove $~} :< removed status
326324 == ::
327325++ diff-human :> name change
328326 $% {$full man/human} :< fully changed name
329− {$true tru/(unit (trel cord (unit cord) cord))} :< changed true name
330327 {$handle han/(unit cord)} :< changed handle
328+ {$true tru/(unit truename)} :< changed true name
331329 == ::
332330```
333331
334−These are, as enforced by Gall, the changes as they happen. This makes it possible for very minimal Hall readers to be implemented that only show a stream of changes, rather than keeping state themselves.
332+These are, as enforced by Gall, the changes as they happen. This makes it possible for very minimal Hall clients to be implemented that only display a stream of changes, rather than keeping state themselves.
335333
336334
337335## Communication between Halls
@@ -345,7 +343,7 @@ To request changes to a story, Halls can send `command`s.
345343```
346344++ command :> effect on story
347345 $% {$publish tos/(list thought)} :< deliver
348− {$present nos/(set knot) dif/diff-status} :< status update
346+ {$present nos/(set term) dif/diff-status} :< status update
349347 :: ... ::
350348 == ::
351349```
@@ -361,14 +359,14 @@ Halls can query other halls. Here's the peer move we send when we open a query o
361359```
362360:* ost.bol :< bone
363361 %peer :< move type
364− /circle/[our-circle]/[host]/[their-circle] :< rumor path
362+ /[our-circle]/[host]/[query-path] :< rumor path
365363 [host %hall] :< query target
366− /circle/[their-circle]/[start]/[end] :< query path
364+ /circle/[their-circle]/[data]/[start]/[end] :< query path
367365== ::
368366```
369367
370368Again, the rumor path is what our Hall uses to identify what query a received message originates from. Our circle is specified so that we know what story is interested in the changes we get.
371−The query path is slightly more interesting. Of course it specifies the name of their story we want to subscribe our story to, but also a "start" and "end". These can (optionally) be used to specify the range of messages we want to get from our query. Once we're out of that range, we stop receiving updates.
369+The query path is slightly more interesting. Of course it specifies the name of their story we want to subscribe our story to, but also a "start" and "end". These can (optionally) be used to specify the range of messages we want to get from our query. Once that range has passed, we stop receiving updates.
372370
373371### Federation
374372
@@ -381,23 +379,27 @@ Along the way so far, we've skipped some parts of structures. Most of these rela
381379 :: ... ::
382380 == ::
383381++ prize :> query result
384− $% {$burden sos/(map knot burden)} :< /burden
382+ $% {$burden sos/(map term burden)} :< /burden
385383 :: ... ::
386384 == ::
387385++ rumor :< query result change
388− $% {$burden nom/knot dif/diff-story} :< /burden
386+ $% {$burden nom/term rum/rumor-story} :< /burden
389387 :: ... ::
390388 == ::
391389++ diff-story ::
392390 $% {$bear bur/burden} :< new inherited story
393− {$burden bur/?} :< burden flag
394391 :: ... ::
395392 == ::
393+++ burden :> full story state
394+ $: gaz/(list telegram) :< all messages
395+ cos/lobby :< loc & rem configs
396+ pes/crowd :< loc & rem presences
397+ == ::
396398```
397399
398400We briefly touched upon how federation works on the higher level. On the lower, this is how things go down.
399401
400−1. When Hall boots on a star or galaxy, it starts querying its parent's (~zod for galaxies) `/burden` path.
402+1. When Hall boots on a star or galaxy, it starts querying its parent's `/burden` path. (Galaxies query ~zod.)
4014032. Upon receiving that query, the parent sends a `%burden` prize containing all state of its channels (fully public circles) to the child. It also subscribes to `/report` on that child.
4024043. When a new story gets created on the parent, its children get a `%burden` rumor with a `%bear` story diff, and they create a local copy of that channel.
4034054. When something about a parent's story changes, a `%burden` rumor is sent to all its children (because they're querying `/burden`). The children apply this change to their local version of the story.
@@ -423,7 +425,7 @@ For brevity, utility arms that aren't a direct and important part of the flow ha
423425
424426(You will find that the origins still use old Gall arms, with some glue code in between. At the time of writing, new Gall has not yet been implemented, so this will have to do.)
425427
426−We will generally only display the delta generation parts of the flow. Delta application is usually implemented simply enough to deduce what it does from looking at the label.
428+We will only display the delta generation parts of the flow. Delta application is usually implemented simply enough to deduce what it does from looking at the label.
427429
428430### Subscriptions
429431
@@ -485,9 +487,9 @@ Hall is neither complete nor perfect. There are features that need to be impleme
485487
486488### Features and functionality
487489
488−To turn talk into a [sustainable social platform](https://urbit.org/fora/posts/~2017.4.26..18.00.25..b93c~/), it needs a number of things.
490+To turn Talk into a [sustainable social platform](https://urbit.org/fora/posts/~2017.4.26..18.00.25..b93c~/), it needs a number of things.
489491
490−Primarily, discoverability of circles. A possible solution for realizing this is making it possible for users to add friends, which would have their Hall subscribe to a list of circles the added friends are in. Of course, one will be able to set joined circles as "private" to keep them from being visible to others.
492+Primarily, discoverability of circles. A possible solution for realizing this is making it possible for users to add friends, which would have their Hall subscribe to a list of circles the added friends are in. The existing public membership functionality can be leveraged for this.
491493
492494Eventually, content self-moderation might need to be implemented. Users would flag their content if it is potentially offensive. Others would easily be able to filter out content that might offend them.
493495This functionality brings its own large sets of challenges that need to be tackled.
@@ -500,7 +502,6 @@ Other changes that might have a fair impact on the functioning of Hall are un/re
500502Smaller functionality that still needs to be implemented includes:
501503* Extended permissions management. Being able to black-/whitelist entire ship classes.
502504* Improved presence functionality. Actually using the presence system, and sending "typing", "idle", etc. statuses.
503−* Flexible on-subscribe scrollback. Some cases may want more than just a day's worth.
504505* Polls.
505506
506507And of course there's a lot Talk, the client, can improve on as well.
@@ -509,7 +510,7 @@ And of course there's a lot Talk, the client, can improve on as well.
509510## Further reading
510511
511512To gain a more thorough understanding of Hall's inner workings, take a look at its source code. It comes with inline documentation.
512−[link]
513+[On Github.](https://github.com/urbit/arvo/blob/master/app/hall.hoon)
513514
514−To see an expansive example of an application that uses Hall, take a look at the code of Talk. It, too, comes with inline documentation.
515−[link]
515+To see an expansive example of a Hall client, take a look at the code of Talk. It, too, comes with inline documentation.
516+[On Github.](https://github.com/urbit/arvo/blob/master/app/talk.hoon)