@@ -0,0 +1,386 @@
4+This document describes the different interfaces Hall provides and the data that is accessible and modifyable through them. Knowledge of the Urbit application model (including [new gall](gall.md)) and #[Hall's architecture](architecture.md) is assumed.
6+While the structures here are given in Hoon, they match fairly closely to their JSON equivalent. Most important to note is that `$%({$x y/z})` becomes accessible as `json.x.y`.
13+ * [/client prize](#client-prize)
14+ * [/client rumor](#client-rumor)
16+ * [/public prize](#public-prize)
17+ * [/public rumor](#public-rumor)
19+ * [/peers prize](#peers-prize)
20+ * [/peers rumor](#peers-rumor)
22+ * [/circle prize](#circle-prize)
23+ * [/circle rumor](#circle-rumor)
25+ * [Circle configuration](#circle-configuration)
26+ * [Messaging](#messaging)
27+ * [Personal metadata](#personal-metadata)
28+ * [Changing shared UI](#changing-shared-ui)
29+ * [Miscellaneous changes](#miscellaneous-changes)
34+Queries are the paths you pass into `%peer` moves. Internally, they get translated to a `++query` structure for easier handling. We'll be giving examples of valid query paths alongside the structures themselves.
38+To be able to keep certain UI elements like glyphs and local nicknames consistent across different Hall clients, they can query Hall for the current UI state.
42+ $% {$client $~} :< shared ui state
50+:> all shared ui state
56+Contains a map of glyphs and the audiences they map to, as well as a map of ships and their locally set nicknames.
59+++ prize :> query result
60+ $% {$client prize-client} :< /client
63+++ prize-client :> shared ui state
64+ $: gys/(jug char audience) :< glyph bindings
65+ nis/(map ship nick) :< local nicknames
71+Contains either a bound or unbound glyph and its target, or a ship with its new ncikname. A `nic`kname of `''` means the associated ship no longer has a nickname set for it.
74+++ rumor :> query result change
75+ $% {$client rum/rumor-client} :< /client
78+++ rumor-client :< changed ui state
79+ $% {$glyph diff-glyph} :< un/bound glyph
80+ {$nick diff-nick} :< changed nickname
82+++ diff-glyph {bin/? gyf/char aud/audience} :< un/bound glyph
83+++ diff-nick {who/ship nic/nick} :< changed nickname
89+To aid in circle discoverability, users can add circles to their "public membership" list. This can then be queried for by, for example, a profile page.
93+ $% {$public $~} :< public memberships
101+:> all public memberships
107+Contains the set of circles the user has on their public list.
110+++ prize :> query result
111+ $% {$public cis/(set circle)} :< /public
118+Contains a circle that was either added or removed from the public list.
121+++ rumor :> query result change
122+ $% {$public add/? cir/circle} :< /public
129+To allow a circle owner to inspect who is actually currently subscribed to their stories, they can issue a query to retrieve subscription data.
133+ $% {$peers nom/naem} :< readers of story
138+Query paths are structured as follows:
147+:> peers for circle %urbit-meta
153+Contains a map of ships and the different queries they currently have active for the selected story.
156+++ prize :> query result
157+ $% {$peers pes/(jar ship query)} :< /peers
164+Contains a ship and a query, and a flag to indicate whether that subscription has started or ended.
167+++ rumor :> query result change
168+ $% {$peers add/? who/ship qer/query} :< /peers
175+Circle queries allow for the retrieving of data from stories. Their messages, configuration, presences, can all be accessed. Since this is a lot of data, there are lots of possibilities for filtering it built in to the query itself.
177+A quick refresher on the difference between "local" and "remote" presence and configuration: "local" means it pertains to the circle itself, "remote" means it pertains to one of its configured sources. The latter is primarily useful to clients when using a circle for aggregation, like the `%inbox`.
181+ $% $: $circle :> story query
182+ nom/naem :< circle name
183+ wer/(unit circle) :< from source
184+ wat/(set circle-data) :< data to get
185+ ran/range :< query duration
189+++ circle-data :> kinds of circle data
190+ $? $grams :< messages
191+ $group-l :< local presence
192+ $group-r :< remote presences
193+ $config-l :< local config
194+ $config-r :< remote configs
196+++ range :> inclusive msg range
197+ %- unit :< ~ means everything
198+ $: hed/place :< start of range
199+ tal/(unit place) :< opt end of range
201+++ place :> range indicators
202+ $% {$da @da} :< date
203+ {$ud @ud} :< message number
207+Query paths are structured as follows:
210+/circle/[circle-name]/(from-circle)/[what/data]/(range-start(/range-end))
211+(from-circle) : optional message source, ~ship/circle
212+[what/data] : one or more of grams, group, group-l, group-r,
213+ : config, config-l, config-r, combined using /
214+(range) : an optional range with an optional end, its points denoted
215+ : in either message number (@ud) or date (@da)
221+:> get all messages from circle %urbit-meta
222+/circle/urbit-meta/grams
223+:> get all messages, all presences and local configs from %urbit-meta
224+/circle/urbit-meta/grams/group/config-l
225+:> get all messages %urbit-meta has heard from its source ~zod/fora
226+/circle/urbit-meta/~zod/fora/grams
227+:> get the first 100 messages from %urbit-meta
228+/circle/urbit-meta/grams/0/99
229+:> get the first 100 messages %urbit-meta has heard from its source ~zod/fora
230+/circle/urbit-meta/~zod/fora/grams/0/99
231+:> get all messages from %urbit-meta, starting now
232+/circle/urbit-meta/grams/group/(scow %da now)
233+:> get all messages from %urbit-meta, starting now, ending at the 100th message
234+/circle/urbit-meta/grams/(scow %da now)/99
235+:> get local presences from %urbit-meta for a week
236+/circle/urbit-meta/group-l/(scow %da now)/(scow %da (add now ~d7))
241+Contains (where applicable) messages in envelopes (with message numbers), local and remote configurations and presences.
244+++ prize :> query result
245+ $% {$circle package} :< /circle
248+++ package :> story state
249+ $: nes/(list envelope) :< messages
250+ cos/lobby :< loc & rem configs
251+ pes/crowd :< loc & rem presences
257+Contains a detailed change description of the data relevant to the query that changed.
258+Messages are wrapped in envelopes to include their sequence number, and note the source they were heard from.
259+Configuration and status changes specify the circle they apply to.
262+++ rumor :> query result change
263+ $% {$circle rum/rumor-story} :< /circle
266+++ rumor-story :> story rumor
267+ $% {$new cof/config} :< new story
268+ {$gram src/circle nev/envelope} :< new/changed message
269+ {$config cir/circle dif/diff-config} :< new/changed config
270+ {$status cir/circle who/ship dif/diff-status} :< new/changed status
271+ {$remove $~} :< removed story
273+++ diff-config :> config change
274+ $% {$full cof/config} :< set w/o side-effects
275+ {$source add/? src/source} :< add/rem sources
276+ {$caption cap/cord} :< changed description
277+ {$filter fit/filter} :< changed filter
278+ {$secure sec/security} :< changed security
279+ {$permit add/? sis/(set ship)} :< add/rem to b/w-list
280+ {$remove $~} :< removed config
282+++ diff-status :> status change
283+ $% {$full sat/status} :< fully changed status
284+ {$presence pec/presence} :< changed presence
285+ {$human dif/diff-human} :< changed name
286+ {$remove $~} :< removed status
288+++ diff-human :> name change
289+ $% {$full man/human} :< fully changed name
290+ {$handle han/(unit cord)} :< changed handle
291+ {$true tru/(unit truename)} :< changed true name
298+Actions can be sent by poking Hall with data marked as `%hall-action`. Actions are used for all user operations. If an error or other unexpected behavior occurs while executing an action, Hall notifies the user by sending an `%app` message to their `%inbox`.
300+### Circle configuration
302+Since all of these apply to a specific circle, they all specify a name `nom` of the circle to operate on.
305+++ action :> user action
306+ $% {$create nom/naem des/cord sec/security} :< create circle
307+ {$delete nom/naem why/(unit cord)} :< delete + announce
308+ {$depict nom/naem des/cord} :< change description
309+ {$filter nom/naem fit/filter} :< change message rules
310+ {$permit nom/naem inv/? sis/(set ship)} :< invite/banish
311+ {$source nom/naem sub/? srs/(set source)} :< un/sub to/from src
316+`%create`: Creates a circle with description `des` and security mode `sec`. If this mode is a whitelist, the user is automatically added to it.
318+`%delete`: Deletes the circle. If a reason `why` is provided, posts that as the last message to the circle before deleting it.
320+`%depict`: Set the description of the circle to `des`.
322+`%filter`: Set the filter (message sanitation rules) for the circle to `fit`.
324+`%permit`: Either invite or banish ships to/from the circle, modifying the access control list accordingly. Regardless of whether this actually makes any changes, sends an `%inv` message to the involved ships' `%inbox`es.
326+`%source`: Add or remove sources to/from the circle, un/subscribing it to/from the `grams`, `group-l` and `config-l` each one.
330+There are two interfaces for telling hall to send a message. The first takes entire `thought`s, the second only `speech`es and the audience to send them to.
333+++ action :> user action
334+ $% {$convey tos/(list thought)} :< post exact
335+ {$phrase aud/audience ses/(list speech)} :< post easy
340+`%convey`: Sends the thoughts to their audiences.
342+`%phrase`: Turns the speeches into thoughts by applying sane defaults for metadata (auto-generated `uid`, `now` for `wen`), and then sends those thoughts.
344+### Personal metadata
346+These concern the presence users have in circles they are participating in.
349+++ action :> user action
350+ $% {$notify aud/audience pes/(unit presence)} :< our presence update
351+ {$naming aud/audience man/human} :< our name update
356+`%notify`: Sets the user's presence in the audience circles to `pes`. A good client will automatically set these based on the user's activity. (`%talk` on typing, `%idle` on idle, `%gone` on sign-off.)
358+`%naming`: Sets the user's name (handle and real name) for the given audience. Good clients can display these in place of ship names.
360+### Changing shared UI
362+When the user makes any changes to shared UI elements (elements that should persist between clients), this has to be communicated to Hall.
365+++ action :> user action
366+ $% {$glyph gyf/char aud/audience bin/?} :< un/bind a glyph
367+ {$nick who/ship nic/nick} :< new identity
373+`%glyph`: Adds or removed a binding of a glyph to an audience.
375+`%nick`: Sets a local nickname for a ship. An empty nickname `''` means the ship has no nickname.
377+### Miscellaneous changes
380+++ action :> user action
381+ $% {$public add/? cir/circle} :< show/hide membership
386+`%public`: Adds or removes a circle to/from the user's public membership list.