@@ -15,7 +15,7 @@ This document outlines the following:
15157. [`sign`](#sign), the responses `%eyre` accepts
16168. [`bolo`](#bolo), the state stored between separate events.
1717
18−# 1. URL structure [#perk]
18+# 1. URL structure <a id="perk"/>
1919There exist several URL forms accepted by `%eyre`.
2020
2121## 1.1 Functional request
@@ -49,7 +49,7 @@ When a new version of a page becomes available, it is useful to propagate it to
4949- `/~/on/[hash].json` retuns `true` when a page may require updating.
5050- `/~/on/[hash].js` is a lightweight script that polls for the above. It is primarily used in error messages.
5151
52−## 1.3 Authentication [#auth]
52+## 1.3 Authentication <a id="auth"/>
5353Authenticated requests are accomplished through sessions, tracked with cookies which are set on the first such request.
5454- `/~/as/[user]/...` is an authenticated request to `...`, where `user` can be a `@p` ship, `'own'`, `'any'`, or `'anon'`.
5555 + `'anon'` is a randomly-generated per-session submarine, and requires no further authentication.
@@ -79,8 +79,8 @@ So far, all the paths specified have been GET requests. Authentication, however,
7979- `POST {oryx, xyro} /~/to/[app]/[mark].json`, where `xyro` is data that will be converted to the `mark`. In the simplest case, `/~/do/hello/json.json` will pass `xyro` through verbatim, sending `[%json xyro]` to the `++poke` arm of app `%hello`.
8080- `POST {oryx, xyro} /~/to/<ship>/[app]/[mark].json` is a foreign message send, as above.
8181
82−## 1.5 Subscriptions [#subs]
83−- `/~/of/[ixor]`[#of-ixor] is an `EventSource`: a conceptually infinite file containing a stream of events. By default, it sends a newline every 30 seconds serving to signal that the connection is alive to both the server and IP middleware.
82+## 1.5 Subscriptions <a id="subs"/>
83+- `/~/of/[ixor]`<a id="of-ixor"/> is an `EventSource`: a conceptually infinite file containing a stream of events. By default, it sends a newline every 30 seconds serving to signal that the connection is alive to both the server and IP middleware.
8484 + `/~/of/[ixor]?poll={n}` is a long-polling fallback interface. Produces event number {n}, blocking until it occurs.
8585
8686Its contexts can be affected by `POST` requests with a body of `{oryx, wire}`, and a query string of `PUT` or `DELETE`. They return either `{mark}`(which may be `null`), or [`{fail, mess}`](#mean-json)
@@ -88,17 +88,17 @@ Its contexts can be affected by `POST` requests with a body of `{oryx, wire}`,
8888- `/~/in/[hash].json` is a dual to [`/~/on`](#on-change). It binds `mod` events, which echo the requesting token.
8989- `/~/is/[app]/path/to.[mark]` binds `rush` events, formatted with a first line of `[app] /path/to`, and the rest containing subscription data. Additionally, `mean` events formatted similarly may arrive, also converted to the relevant mark.
9090
91−## 1.6 Ablative [#temp]
91+## 1.6 Ablative <a id="temp"/>
9292These interfaces will temporarily exist to aid development, and are to be considered unstable.
9393- `/~/debug/...` access normally inaccessible pages. For example, `/~/debug/as.html` will present the login page, regardless of current session status.
9494
95−# 2. Client state [#client]
95+# 2. Client state <a id="client"/>
9696Some information is stored on, and provided to, browser clients
9797
9898## 2.1 Cookies
9999Authenticated users receive a cookie on the domain of `*.urbit.org`. The cookie contains a client session token, keyed by the serving ship.
100100
101−## 2.2 Authentication [#auth-json]
101+## 2.2 Authentication <a id="auth-json"/>
102102It is common(e.g. by the `%urb` mark) to set window.urb to the contents of `/~/auth.json`:
103103- `ship` is the serving ship
104104- `oryx` is a unique CSRF token that identifies this view, bound to the session cookie
@@ -114,7 +114,7 @@ To this object, `/main/lib/urb.js` adds helpers:
114114- `drop({path,app?=urb.app}, cb?)` pulls the subscription
115115- `util` is an object containing methods for converting between JavaScript types and Hoon atom odors.
116116
117−# 3. Requests [#kiss]
117+# 3. Requests <a id="kiss"/>
118118
119119## `[%born port=@ud]`, unix init
120120When the `vere` process is re/started, a TCP port is bound, HTTP requests on which are the scope of this document. The `%born` gift informs eyre of this occurrence, which in turn updates [its state.](#bolo)
@@ -144,7 +144,7 @@ After `r` is parsed to a `purl`, the `pork`(relative path) determines the resour
144144- `/~/at` and `/~/auth.json` generate a new `oryx` and store it in the [session state](#sink).
145145- `/~/in` and `/~/is` affect [view state](#stem), possibly sending subscriptions or unsubscriptions to `%f` and `%g` respectively, and are generated from view state.
146146- `/~/on` is saved to the `bolo` by `hash`, and translated to a [`%wasp` note](#wasp).
147−- `/~/of` fails if the `ixor` is unknown, and otherwise is stored in the `ixor`, receiving a partial response and all events after its [last-seen header](#). If it has a `poll` parameter, the response is full, and only occurs if the body is non-empty. Otherwise the oryx is saved as a (live)[#live] request in case of cancellation.
147+- `/~/of` fails if the `ixor` is unknown, and otherwise is stored in the `ixor`, receiving a partial response and all events after its [last-seen header](#). If it has a `poll` parameter, the response is full, and only occurs if the body is non-empty. Otherwise the oryx is saved as a [live](#live) request in case of cancellation.
148148- `/~/to` transforms into a [`%g` message](#mess).
149149
150150**Gifts given in response:** a [`%thou`](), or a [`%that`](#that) followed by multiple [`%thar`]()s.
@@ -165,10 +165,10 @@ Sometimes, messages are received from other ships. They are expected to take the
165165
166166**Gifts given in response:** [`%nice` or `%mean`](#ack).
167167
168−### 3.4.1 `gram` [#gram]
168+### 3.4.1 `gram` <a id="gram"/>
169169
170−There are three messages of note, all concerning authentication [#foreign]
171−- `[/lon ses]` [#lon] is a login request, which contains the session wishing to authenticate.
170+There are three messages of note, all concerning authentication <a id="foreign"/>
171+- `[/lon ses]` <a id="lon"/> is a login request, which contains the session wishing to authenticate.
172172- if the session is already authorized, a reply of `[/aut ses]` from (%eyre on) a foreign ship prescribes that the session is henceforth allowed to act on its behalf.
173173All waiting `/~/as` are resolved as succesful.
174174- otherwise, `[/hat ses hart]` contains the ship's preferred hostname. This can then be used to redirect the client.
@@ -176,8 +176,8 @@ All waiting `/~/as` are given `307 Redirect`s to `/~/am` on the provided host.
176176
177177**Gifts given in response:** nice?
178178
179−# 4. Responses [#gift]
180−## 4.1 `[%nice ~]`, `[%mean ares]`, network acknowledgement [#ack]
179+# 4. Responses <a id="gift"/>
180+## 4.1 `[%nice ~]`, `[%mean ares]`, network acknowledgement <a id="ack"/>
181181A `%nice` is given upon receiving an [ames message](#gram), indicating succesful receipt. `%mean` is currently unused directly, but reserved for error conditions.
182182
183183## `[%sigh p=cage]`, inbound http response
@@ -189,35 +189,35 @@ Most requests are served with one coherent response, consisting of
189189- `q=mess`, response headers
190190- `r=(unit octs)`, an optional body
191191
192−## 4.3 `[%that httr]`, partial HTTP response [#that]
192+## 4.3 `[%that httr]`, partial HTTP response <a id="that"/>
193193[EventStream responses](#of-ixor) consist of multiple sequential chunks. Treated as `%thou`, except the request is kept open.
194194
195−## 4.4 `[%thar (unit octs)]`, partial HTTP body [#thar]
195+## 4.4 `[%thar (unit octs)]`, partial HTTP body <a id="thar"/>
196196Complementing `%that`, `%thar` is a body chunk, containing an event. An empty `%thar` signals for the connection to be closed.
197197
198198Body chunks, besides `[1 '\0a']`(a heartbeat newline), are encoded from `even` events. The stem becomes the [`event` field](#eventsource), and the content, `data` lines.
199199
200−### 4.4.1 `even`, event types [#even]
200+### 4.4.1 `even`, event types <a id="even"/>
201201There are three events that a [client subscription](#subs) will be given.
202202
203−- `[%news hash]`[#even-news] is a `%f` update, and contains the relevant dependency token.
204−- `[%rush [term path] wain]`[#even-rush] is sourced subscription data.
203+- `[%news hash]`<a id="even-news"/> is a `%f` update, and contains the relevant dependency token.
204+- `[%rush [term path] wain]`<a id="even-rush"/> is sourced subscription data.
205205- `[%mean [term path] ares]` is a sourced subscription error.
206206
207−# 5. Vane requests [#note]
207+# 5. Vane requests <a id="note"/>
208208## 5.1 ``[%a %wont sock `[path *]`gram]``, outbound message
209209The `%a` interface provides conveyance of [messages](#gram) over UDP.
210210
211211Signs a `%woot` upon message arrival.
212212
213−## 5.2 `[%b ?(%wait %rest) time]`, timeout set/unset [#wait]
213+## 5.2 `[%b ?(%wait %rest) time]`, timeout set/unset <a id="wait"/>
214214All open [subscriptions](#of-ixor) require a "heartbeat" newline every `~s30`. When this fails to arrive, a complementary timer is set for `~m1`, after which the client is considered to have departed.
215215The `%b` timer interface is used to schedule the next such event, or cancel past scheduled ones when a connection closes.
216216
217217Signs a `%wake` upon timer activation.
218218
219−## 5.3 `[%f %wasp @uvI]`, dependency listen [#wasp]
220−Knowledge of filesystem changes, requested by `/~/on` and `/~/in`, is requested the `%wasp` note. It contains the hash token which idenitifes a set of dependencies to query. Saved as a (live)[#live] request in case of cancellation when caused by `/~/on`.
219+## 5.3 `[%f %wasp @uvI]`, dependency listen <a id="wasp"/>
220+Knowledge of filesystem changes, requested by `/~/on` and `/~/in`, is requested the `%wasp` note. It contains the hash token which idenitifes a set of dependencies to query. Saved as a (live[live](#live)#live] request in case of cancellation when caused by `/~/on`.
221221
222222Signs a `%writ` upon change.
223223
@@ -229,12 +229,12 @@ Signs a `%made` containing the computation result.
229229The `silk`s used are as follows:
230230
231231### `[%cast %mime %boil mark beam [%web span ~]]`, file load
232−The simplest functional request is the construction of a page. Saved as a (live)[#live] request in case of cancellation.
232+The simplest functional request is the construction of a page. Saved as a [live](#live) request in case of cancellation.
233233- The `mark` is the request extension, defaulting to `%html`.
234234- A `beam`(path in `%clay`) is decoded from the request path.
235235- A `/web/<nyp ced quy>` virtual path is appended, span-encoding method, auth, and query string.
236236
237−### `[%cast mark %done ~ cage]`, convert [#done]
237+### `[%cast mark %done ~ cage]`, convert <a id="done"/>
238238This is used when communicating with apps, in both directions.
239239- Client messages are encoded as JSON objects, but can contain many different marks. Ones sent to non-`json.json` endpoints are `%cast` to he relevant mark, with a `cage` of `[%json p:!>(*json) jon]`, prior to being sent onwards to applications with `[%g %mess]`.
240240- Subscription responses also come in arbitrary marks, but are required to be sent as whichever mark an endpoint is subscribed to. They get `%cast` prior to being sent back as a `%that` EventSource segment.
@@ -242,12 +242,12 @@ This is used when communicating with apps, in both directions.
242242## 5.5 `%g`, app actions
243243The end goal of many a userspace `hymn.hook` is to provide UI for a `%gall` app. To accommodate this, various functionality needs to be interfaced with.
244244
245−### `[%mess hapt ship cage]`, app message [#mess]
245+### `[%mess hapt ship cage]`, app message <a id="mess"/>
246246After a `/~/to` POST has been received, and possibly converted to the correct mark, it is sent to `%g` for processing. The `hapt` is the destination, the `ship` is the source, the `cage` is the marked message data.
247247
248248Signs a `%nice` or `%mean`, in userspace or upon crashing.
249249
250−### `[%show hapt ship path]`, app subscription[#show]
250+### `[%show hapt ship path]`, app subscription<a id="show"/>
251251An `/~/is` PUT, if not already registered, results in a new subscription. A request for such contains the destination `hapt`, requesting `ship`, and app-internal `path`.
252252
253253Signs a `%nice` on init, `%rush` on data, and a `%mean` in subscription termination.
@@ -262,13 +262,13 @@ An `/~/is` DELETE is used to remove a subscription, and is converted straightfor
262262
263263Signs an empty `%mean` for each open subscription that is closed.
264264
265−# 6. In-flight metadata [#whir]
265+# 6. In-flight metadata <a id="whir"/>
266266Various state can be associated with requests, but not necessarily be returned in responses to them.
267267
268−## 6.1 `~`, dropthrough [#wire-drop]
268+## 6.1 `~`, dropthrough <a id="wire-drop"/>
269269If the response should be sent statelessly further up the duct, the `wire` is empty. This is used in `%f` pure functional page generation.
270270
271−## 6.2 `[?(%y %n) ...]`, stability [#wire-live]
271+## 6.2 `[?(%y %n) ...]`, stability <a id="wire-live"/>
272272The first element of a [`%b` timer](#wait) path distinguishes between live(%y) and dying(%n) channels.
273273
274274## 6.3 `/of/[ixor]`, view
@@ -277,13 +277,13 @@ Designates which stream to act upon. Present on `%b` timer cards.
277277## 6.4 `/on/<deps>`
278278Present on `%f` dependency news. Looked up in [the state](#bolo) to see if any response is necessary.
279279
280−## 6.5 `/to/<hasp>/<ship>`, app [#wire-to]
280+## 6.5 `/to/<hasp>/<ship>`, app <a id="wire-to"/>
281281Present on `%f` translations of message marks
282282
283−## 6.6 `/is/[ixor]/{hasp path}`, subscription [#wire-is]
283+## 6.6 `/is/[ixor]/{hasp path}`, subscription <a id="wire-is"/>
284284Subscription requests. Present on `%g` subscription requests, and `%f` translations of [`%rush` subscription data](#show).
285285
286−# 7. Vane responses [#sign]
286+# 7. Vane responses <a id="sign"/>
287287The goal of requests is to cause some manner of result. Specifically,
288288
289289## 7.1 `[%a %woot ship coop]`, acknowledgement
@@ -311,11 +311,11 @@ The former is [served](#mime) back to the requester(i.e. the remaining duct), an
311311### 7.5 `[%rush cage]`, subscription data
312312A `%rush` arrives on a [subscription wire](#wire-is), and is then sent [for conversion](#done) to the correct mark. An unexpected `%rush` is `%nuke`d.
313313
314−# 8. Server state [#bolo]
314+# 8. Server state <a id="bolo"/>
315315There is a quantity of data that persists between events.
316316
317317## 8.1 Global
318−- `path` [#prefix] the default path which is prepended to relative plain requests. Initialized to `/<our>`, the serving ship; this interprets the first element of requests as a desk, and injects a `case` of `0`.
318+- `path` <a id="prefix"/> the default path which is prepended to relative plain requests. Initialized to `/<our>`, the serving ship; this interprets the first element of requests as a desk, and injects a `case` of `0`.
319319- `(jar ship hart)` remembered hostnames in order of preference, made accessible through `.^`
320320 + The default values(for self) are `http://<ship>.urbit.org:80` if not on a fake network, followed by `https://0.0.0.0:[port]`.
321321- `(jug deps (each duct oryx))`, `/~/on` and `/~/in` endpoints listening to `%c` updates.
@@ -325,24 +325,24 @@ There is a quantity of data that persists between events.
325325- `(map hole sink)`, session state.
326326- `(map hole ,[ship ?])`, foreign session names, along with their origin ships and whether they are authorized to act on our behalf.
327327
328−## 8.2 `live`, per-request state [#live]
328+## 8.2 `live`, per-request state <a id="live"/>
329329To honor request cancellations, each unserved request must track which effect it is causing.
330330+ `[%exec whir]` if it is a ford data request
331331+ `[%wasp (list @uvH)]` if it is a ford dependency poll
332332+ `[%xeno ship]` if this is a proxied request
333333+ `[%poll ixor]` if this is a session long-poll
334334
335−## 8.3 `sink`, per-session state [#sink]
335+## 8.3 `sink`, per-session state <a id="sink"/>
336336Each `hole` has associated authentication state.
337337- `priv`, a random secret that verifies the session, stored in cookie.
338338- `[ship (set ship)]`, the `ship` a session is acting as and any others it has been authorized with.
339339- `(jug ship ,[path duct])`, authentication `/~/as` requests waiting on foreign ships.
340340- `(set oryx)`, views associated with this session. Dual of `hole` in `stem`.
341341
342−## 8.4 `stem`, per-view state [#stem]
342+## 8.4 `stem`, per-view state <a id="stem"/>
343343Each `oryx` has active subscription state.
344344- `hole`, session in which this view resides. Dual of `(set oryx)` in `sink`.
345−- `ixor`[#ixor], a cached hash of the `oryx` that is used as a subscription id, by the `/~/of` EventStream.
345+- `ixor`<a id="ixor"/>, a cached hash of the `oryx` that is used as a subscription id, by the `/~/of` EventStream.
346346- `[,@u (map ,@u even)]`, queued [events](#even). Has a maximum size.
347347- `(unit ,[duct @u ?])`, http connection, its last received event, and whether it is a long-poll request.
348348- `(set deps)`, subscribed `/~/in` points. Mirrored in `bolo`.
@@ -351,11 +351,11 @@ Each `oryx` has active subscription state.
351351
352352# Appendix A: Glossary
353353- An `oryx` is a CSRF token used for [authenticated requests](#auth)
354−- `mean.json`[#mean-json] is a rendering of hoon `ares`: an error message formatted as `{fail:'type',mess:"Error message"}`
355−- `urb.js`[#urb-js] is the standard client-side implementation of the `%eyre` protocols, normally found in `/=main=/lib`
356−- The act of "serving" \[#mime], refers to the wrapping of a `%mime` cage in an HTTP `200 Success` response, and errors or other marks being [sent to ford](#done) for conversion. Inside a `sign`, this conversion occurs along the same [`wire`](#wire); otherwise, the `wire` is [empty](#wire-drop).
354+- `mean.json`<a id="mean-json"/> is a rendering of hoon `ares`: an error message formatted as `{fail:'type',mess:"Error message"}`
355+- `urb.js`<a id="urb-js"/> is the standard client-side implementation of the `%eyre` protocols, normally found in `/=main=/lib`
356+- The act of "serving" \<a id="mime"/>, refers to the wrapping of a `%mime` cage in an HTTP `200 Success` response, and errors or other marks being [sent to ford](#done) for conversion. Inside a `sign`, this conversion occurs along the same [`wire`](#wire); otherwise, the `wire` is [empty](#wire-drop).
357357
358−# Appendix B: EventSource [#eventsource]
358+# Appendix B: EventSource <a id="eventsource"/>
359359For more information, see <http://dev.w3.org/html5/eventsource/>
360360
361361An EventSource is a stream of events, encoded in a conceptually infinite `GET` request. Each event is formatted as