@@ -47,7 +47,8 @@ Runtime
4747Let us follow the loading of a simple cli app, as it bounces from
4848browser to server to browser and back.
4949
50−### Initial request ;a(id "init");
50+<span id="init"></span>
51+### Initial request
5152
5253An http request for `http://sampel-sipnym.urbit.org/cli` will be [redirected](dns)
5354to the `%eyre` on ~sampel-sipnym, and come in as a `%this` kiss.
@@ -141,7 +142,7 @@ from request data.
141142Returning to `++process-auth`, `%get` checks if the yac is authenticated with
142143the requested credentials(`anon` requests are always granted), which for the
143144fresh new `cyst` is not the case (more on success [later](#auth-ok)). Unless
144−authentiacting as a [foreign ship](#xeno), the only thing left is to
145+authenticating as a [foreign ship](#xeno), the only thing left is to
145146`++show-login-page`, which detects that the requested resource is not `%html`,
146147and produces a `%red` pest. For `%js`, `%red`irections `++resolve` to
147148`++auth-redir:js`, a line of javascript which prepends `/~~` to the url path.
@@ -182,7 +183,8 @@ to a `[%auth %try {password}]` perk. `%get:process-auth` checks it against
182183serves a fresh `auth.json` which reflects the changed `user`. Upon receiving
183184this, the page is refreshed to retry the original request.
184185
185−### Post-authentication: app communication. <a id="auth-ok"/>
186+<span id="auth-ok"></span>
187+### Post-authentication: app communication.
186188
187189Upon refresh, `/~~/cli` brings us for the third time to `%get:process-auth`, but
188190this time the cookie is set, and the `yac` fetched contains the serving ship as
@@ -205,7 +207,8 @@ of `oryx` that identifies the connection. `++as-aux-request`, an `%is` is a
205207`++add-subs:ix`, the ix core fetched `++for-view` by hashing the request
206208`++oryx-to-ixor`.
207209
208−<a id="ixor"/> A view has all the state associated with a client that must be
210+<span id="view-ixor"></span>
211+A view has all the state associated with a client that must be
209212remembered between events. In this case, this is what app/path the request duct
210213is associated with; but mainly, `++add-subs:ix` will `pass-note` to `%gall` so
211214it `%show`s the data on the path, current and future.
@@ -239,14 +242,16 @@ would occur first, and `%made:axon` would send the gall message proper. In
239242either case, eventually a `%mean` or `%nice` arrives, is encoded as json, and
240243sent to the client callback.
241244
242−## A path not taken: magic filenames <a id="mage"/>
245+<span id="mage"></span>
246+## A path not taken: magic filenames
243247
244248The `/robots.txt` and `/favicon.(ico|png)` files are static, and served
245249immediately when caught by a `++parse`.
246250
247251XX index.html?
248252
249−## A path not taken: foreign auth <a id="xeno"/>
253+<span id="xeno"></span>
254+## A path not taken: foreign auth
250255
251256While this example details a login `/~/as/own`, it is possible to be
252257authenticated as any ship on the network. A request for such seen in
@@ -276,7 +281,8 @@ and sending `%g %nuke`.
276281
277282XX unmentioned arms: abet, add-poll, adit, ames-gram, anon, ares-to-json, bolo, cyst, doze, even, ford-kill, get-mean, gift, give-json, give-thou, gram, hapt, hasp, host-to-ship, ix, ixor, js, kiss, load, mean-json, move, note, pass-note, perk, perk-auth, pest, poke-test, print-subs, render-tang, resp, root-beak, scry, ses-authed, ses-ya, sign, silk, sine, stay, stem, teba, titl, to-oryx, urb, wait-era, wake, whir, wush, xml, ya, ye
278283
279−### Appendix A: DNS <a id="dns"/>
284+<span id="dns"></span>
285+### Appendix A: DNS
280286
281287The `*.urbit.org` domain can be used to access destroyers and cruisers. In the
282288common case oh hosted ships, this is done by dynamic DNS directly to the hosting
@@ -344,8 +350,8 @@ When a new version of a page becomes available, it is useful to propagate it to
344350- `/~/on/[hash].json` retuns `true` when a page may require updating.
345351- `/~/on/[hash].js` is a lightweight script that polls for the above. It is primarily used in error messages.
346352
347−;a(id "auth");
348−## 1.3 Authentication
353+<span id="auth"></span>
354+### 1.3 Authentication
349355
350356Authenticated requests are accomplished through sessions, tracked with cookies which are set on the first such request.
351357- `/~/as/[user]/...` is an authenticated request to `...`, where `user` can be a `@p` ship, `'own'`, `'any'`, or `'anon'`.
@@ -370,11 +376,10 @@ So far, all the paths specified have been GET requests. Authentication, however,
370376- `POST {oryx, wire, xyro} /~/to/[app]/[mark].json`, where `xyro` is data that will be converted to the `mark`. In the simplest case, `/~/to/hello/json.json` will pass `xyro` through verbatim, sending `[%json xyro]` to the `++poke` arm of app `%hello`.
371377- `POST {oryx, wire, xyro} /~/to/<ship>/[app]/[mark].json` is a foreign message send, as above.
372378
373−;a(id "subs");
379+<span id="subs"></span>
374380### 1.5 Subscriptions
375381
376−;a(id "of-ixor");
377−
382+<span id="of-ixor"></span>
378383- `/~/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.
379384 + `/~/of/[ixor]?poll={n}` is a long-polling fallback interface. Produces event number `{n}`, blocking until it occurs. Its 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)
380385- `/~/in/[hash].json` is a dual to [`/~/on`](#on-change). It binds `mod` events, which echo the requesting token.
@@ -382,14 +387,15 @@ So far, all the paths specified have been GET requests. Authentication, however,
382387
383388
384389
385−;a(id "temp");
390+<span id="temp"></span>
386391### 1.6 Ablative
387392
388393These interfaces will temporarily exist to aid development, and are to be considered unstable.
389394- `/~/debug/...` access normally inaccessible pages. For example, `/~/debug/as.html` will present the login page, regardless of current session status.
390395
391396
392−## 2. Client state ;a(id "client");
397+<span id="client"></span>
398+## 2. Client state
393399
394400Some information is stored on, and provided to, browser clients
395401
@@ -397,7 +403,8 @@ Some information is stored on, and provided to, browser clients
397403
398404Authenticated users receive a cookie on the domain of `*.urbit.org`. The cookie contains a client session token, keyed by the serving ship.
399405
400−### 2.2 Authentication ;a(id "auth-json");
406+<span id="auth-json"></span>
407+### 2.2 Authentication
401408
402409It is common(e.g. by the `%urb` mark) to set window.urb to the contents of `/~/auth.json`:
403410- `ship` is the serving ship
@@ -415,7 +422,8 @@ To this object, `/main/lib/urb.js` adds helpers:
415422- `drop({path,app?=urb.app}, cb?)` pulls the subscription
416423- `util` is an object containing methods for converting between JavaScript types and Hoon atom odors.
417424
418−## 3. Requests ;a(id "kiss");
425+<span id="kiss"></span>
426+## 3. Requests
419427
420428## `[%born port=@ud]`, unix init
421429
@@ -477,18 +485,23 @@ Sometimes, messages are received from other ships. They are expected to take the
477485
478486*Gifts given in response:* [`%nice` or `%mean`](#ack).
479487
480−#### 3.4.1 `gram` <a id="gram"/>
488+<span id="gram"></span>
489+#### 3.4.1 `gram`
481490
482−There are three messages of note, all concerning authentication <a id="foreign"/>
483−- `[/lon ses]` <a id="lon"/> is a login request, which contains the session wishing to authenticate.
491+<span id="foreign"></span>
492+There are three messages of note, all concerning authentication
493+<span id="lon"></span>
494+- `[/lon ses]` is a login request, which contains the session wishing to authenticate.
484495- 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. All waiting `/~/as` are resolved as successful.
485496- otherwise, `[/hat ses hart]` contains the ship's preferred hostname. This can then be used to redirect the client. All waiting `/~/as` are given `307 Redirect`s to `/~/am` on the provided host.
486497
487498*Gifts given in response:* nice?
488499
489−## 4. Responses ;a(id "gift");
500+<span id="gift"></span>
501+## 4. Responses
490502
491−### 4.1 `[%nice ~]`, `[%mean ares]`, network acknowledgement ;a(id "ack");
503+<span id="ack"></span>
504+### 4.1 `[%nice ~]`, `[%mean ares]`, network acknowledgement
492505
493506A `%nice` is given upon receiving an [ames message](#gram), indicating succesful receipt. `%mean` is currently unused directly, but reserved for error conditions.
494507
@@ -503,25 +516,31 @@ Most requests are served with one coherent response, consisting of
503516- `q=mess`, response headers
504517- `r=(unit octs)`, an optional body
505518
506−### 4.3 `[%that httr]`, partial HTTP response ;a(id "that");
519+<span id="that"></span>
520+### 4.3 `[%that httr]`, partial HTTP response
507521
508522[EventStream responses](#of-ixor) consist of multiple sequential chunks. Treated as `%thou`, except the request is kept open.
509523
510−### 4.4 `[%thar (unit octs)]`, partial HTTP body ;a(id "thar");
524+<span id="thar"></span>
525+### 4.4 `[%thar (unit octs)]`, partial HTTP body
511526
512527Complementing `%that`, `%thar` is a body chunk, containing an event. An empty `%thar` signals for the connection to be closed.
513528
514529Body chunks, besides `[1 '\0a']`(a heartbeat newline), are encoded from `even` events. The stem becomes the [`event` field](#eventsource), and the content, `data` lines.
515530
516−#### 4.4.1 `even`, event types ;a(id "even");
531+<span id="even"></span>
532+#### 4.4.1 `even`, event types
517533
518534There are three events that a [client subscription](#subs) will be given.
519535
520−- `[%news hash]`;a(id "even-news"); is a `%f` update, and contains the relevant dependency token.
521−- `[%rush [term path] wain]` ;a(id "even-rush"); is sourced subscription data.
536+<span id="even-news"></span>
537+- `[%news hash]` is a `%f` update, and contains the relevant dependency token.
538+<span id="even-rush"></span>
539+- `[%rush [term path] wain]` is sourced subscription data.
522540- `[%mean [term path] ares]` is a sourced subscription error.
523541
524−## 5. Vane requests ;a(id "note");
542+<span id="note"></span>
543+## 5. Vane requests
525544
526545### 5.1 ``[%a %wont sock `[path *]`gram]``, outbound message
527546
@@ -529,14 +548,16 @@ The `%a` interface provides conveyance of [messages](#gram) over UDP.
529548
530549Signs a `%woot` upon message arrival.
531550
532−### 5.2 `[%b ?(%wait %rest) time]`, timeout set/unset ;a(id "wait");
551+<span id="wait"></span>
552+### 5.2 `[%b ?(%wait %rest) time]`, timeout set/unset
533553
534554All 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.
535555The `%b` timer interface is used to schedule the next such event, or cancel past scheduled ones when a connection closes.
536556
537557Signs a `%wake` upon timer activation.
538558
539−### 5.3 `[%f %wasp @uvI]`, dependency listen ;a(id "wasp");
559+<span id="wasp"></span>
560+### 5.3 `[%f %wasp @uvI]`, dependency listen
540561
541562Knowledge of filesystem changes, requested by `/~/on` and `/~/in`, is requested the `%wasp` note. It contains the hash token which identifies a set of dependencies to query. Saved as a (live[live](#live)#live] request in case of cancellation when caused by `/~/on`.
542563
@@ -557,7 +578,8 @@ The simplest functional request is the construction of a page. Saved as a [live]
557578- A `beam`(path in `%clay`) is decoded from the request path.
558579- A `/web/<nyp ced quy>` virtual path is appended, span-encoding method, auth, and query string.
559580
560−### `[%cast mark %done ~ cage]`, convert ;a(id "done");
581+<span id="done"></span>
582+### `[%cast mark %done ~ cage]`, convert
561583
562584This is used when communicating with apps, in both directions.
563585- 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]`.
@@ -567,13 +589,15 @@ This is used when communicating with apps, in both directions.
567589
568590The 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.
569591
570−### `[%mess hapt ship cage]`, app message ;a(id "mess");
592+<span id="mess"></span>
593+### `[%mess hapt ship cage]`, app message
571594
572595After 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.
573596
574597Signs a `%nice` or `%mean`, in userspace or upon crashing.
575598
576−### `[%show hapt ship path]`, app subscription ;a(id "show");
599+<span id="show"></span>
600+### `[%show hapt ship path]`, app subscription
577601
578602An `/~/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`.
579603
@@ -591,15 +615,18 @@ An `/~/is` DELETE is used to remove a subscription, and is converted straightfor
591615
592616Signs an empty `%mean` for each open subscription that is closed.
593617
594−## 6. In-flight metadata ;a(id "whir");
618+<span id="whir"></span>
619+## 6. In-flight metadata
595620
596621Various state can be associated with requests, but not necessarily be returned in responses to them.
597622
598−### 6.1 `~`, dropthrough ;a(id "wire-drop");
623+<span id="wire-drop"></span>
624+### 6.1 `~`, dropthrough
599625
600626If the response should be sent statelessly further up the duct, the `wire` is empty. This is used in `%f` pure functional page generation.
601627
602−### 6.2 `[?(%y %n) ...]`, stability ;a(id "wire-live");
628+<span id="wire-live"></span>
629+### 6.2 `[?(%y %n) ...]`, stability
603630
604631The first element of a [`%b` timer](#wait) path distinguishes between live(%y) and dying(%n) channels.
605632
@@ -611,15 +638,18 @@ Designates which stream to act upon. Present on `%b` timer cards.
611638
612639Present on `%f` dependency news. Looked up in [the state](#bolo) to see if any response is necessary.
613640
614−### 6.5 `/to/<hasp>/<ship>`, app ;a(id "wire-to");
641+<span id="wire-to"></span>
642+### 6.5 `/to/<hasp>/<ship>`, app
615643
616644Present on `%f` translations of message marks
617645
618−### 6.6 `/is/[ixor]/{hasp path}`, subscription ;a(id "wire-is");
646+<span id="wire-is"></span>
647+### 6.6 `/is/[ixor]/{hasp path}`, subscription
619648
620649Subscription requests. Present on `%g` subscription requests, and `%f` translations of [`%rush` subscription data](#show).
621650
622−## 7. Vane responses ;a(id "sign");
651+<span id="sign"></span>
652+## 7. Vane responses
623653
624654The goal of requests is to cause some manner of result. Specifically,
625655
@@ -655,13 +685,15 @@ The former is [served](#mime) back to the requester(i.e. the remaining duct), an
655685
656686A `%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.
657687
658−## 8. Server state ;a(id "bolo");
688+<span id="bolo"></span>
689+## 8. Server state
659690
660691There is a quantity of data that persists between events.
661692
662693### 8.1 Global
663694
664−- `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`.
695+<span id="prefix"></span>
696+- `path` 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`.
665697- `(jar ship hart)` remembered hostnames in order of preference, made accessible through `.^`
666698 + 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]`.
667699- `(jug deps (each duct oryx))`, `/~/on` and `/~/in` endpoints listening to `%c` updates.
@@ -671,7 +703,8 @@ There is a quantity of data that persists between events.
671703- `(map hole sink)`, session state.
672704- `(map hole ,[ship ?])`, foreign session names, along with their origin ships and whether they are authorized to act on our behalf.
673705
674−### 8.2 `live`, per-request state ;a(id "live");
706+<span id="live"></span>
707+### 8.2 `live`, per-request state
675708
676709To honor request cancellations, each unserved request must track which effect it is causing.
677710+ `[%exec whir]` if it is a ford data request
@@ -679,7 +712,8 @@ To honor request cancellations, each unserved request must track which effect it
679712+ `[%xeno ship]` if this is a proxied request
680713+ `[%poll ixor]` if this is a session long-poll
681714
682−### 8.3 `sink`, per-session state ;a(id "sink");
715+<span id="sink"></span>
716+### 8.3 `sink`, per-session state
683717
684718Each `hole` has associated authentication state.
685719- `priv`, a random secret that verifies the session, stored in cookie.
@@ -687,11 +721,13 @@ Each `hole` has associated authentication state.
687721- `(jug ship ,[path duct])`, authentication `/~/as` requests waiting on foreign ships.
688722- `(set oryx)`, views associated with this session. Dual of `hole` in `stem`.
689723
690−### 8.4 `stem`, per-view state ;a(id "stem");
724+<span id="stem"></span>
725+### 8.4 `stem`, per-view state
691726
692727Each `oryx` has active subscription state.
693728- `hole`, session in which this view resides. Dual of `(set oryx)` in `sink`.
694−- `ixor` ;a(id "ixor"); , a cached hash of the `oryx` that is used as a subscription id, by the `/~/of` EventStream.
729+<span id="ixor"></span>
730+- `ixor`, a cached hash of the `oryx` that is used as a subscription id, by the `/~/of` EventStream.
695731- `[,@u (map ,@u even)]`, queued [events](#even). Has a maximum size.
696732- `(unit ,[duct @u ?])`, http connection, its last received event, and whether it is a long-poll request.
697733- `(set deps)`, subscribed `/~/in` points. Mirrored in `bolo`.
@@ -701,11 +737,15 @@ Each `oryx` has active subscription state.
701737## Appendix A: Glossary
702738
703739- An `oryx` is a CSRF token used for [authenticated requests](#auth)
704−- `mean.json` ;a(id "mean-json"); is a rendering of hoon `ares`: an error message formatted as `{fail:'type',mess:"Error message"}`
705−- `urb.js` ;a(id "urb-js"); is the standard client-side implementation of the `%eyre` protocols, normally found in `/=main=/lib`
706−- 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).
707−
708−## Appendix B: EventSource ;a(id "eventsource");
740+<span id="mean-json"></span>
741+- `mean.json` is a rendering of hoon `ares`: an error message formatted as `{fail:'type',mess:"Error message"}`
742+<span id="urb-js"></span>
743+- `urb.js` is the standard client-side implementation of the `%eyre` protocols, normally found in `/=main=/lib`
744+<span id="mime"></span>
745+- The act of "serving", 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).
746+
747+<span id="eventsource"></span>
748+## Appendix B: EventSource
709749
710750UNIMPLEMENTED
711751