@@ -47,7 +47,6 @@ Runtime
4747Let us follow the loading of a simple cli app, as it bounces from
4848browser to server to browser and back.
4949
50−<span id="init"></span>
5150### Initial request
5251
5352An http request for `http://sampel-sipnym.urbit.org/cli` will be [redirected](dns)
@@ -183,7 +182,6 @@ to a `[%auth %try {password}]` perk. `%get:process-auth` checks it against
183182serves a fresh `auth.json` which reflects the changed `user`. Upon receiving
184183this, the page is refreshed to retry the original request.
185184
186−<span id="auth-ok"></span>
187185### Post-authentication: app communication.
188186
189187Upon refresh, `/~~/cli` brings us for the third time to `%get:process-auth`, but
@@ -207,7 +205,6 @@ of `oryx` that identifies the connection. `++as-aux-request`, an `%is` is a
207205`++add-subs:ix`, the ix core fetched `++for-view` by hashing the request
208206`++oryx-to-ixor`.
209207
210−<span id="view-ixor"></span>
211208A view has all the state associated with a client that must be
212209remembered between events. In this case, this is what app/path the request duct
213210is associated with; but mainly, `++add-subs:ix` will `pass-note` to `%gall` so
@@ -242,7 +239,6 @@ would occur first, and `%made:axon` would send the gall message proper. In
242239either case, eventually a `%mean` or `%nice` arrives, is encoded as json, and
243240sent to the client callback.
244241
245−<span id="mage"></span>
246242## A path not taken: magic filenames
247243
248244The `/robots.txt` and `/favicon.(ico|png)` files are static, and served
@@ -250,7 +246,6 @@ immediately when caught by a `++parse`.
250246
251247XX index.html?
252248
253−<span id="xeno"></span>
254249## A path not taken: foreign auth
255250
256251While this example details a login `/~/as/own`, it is possible to be
@@ -281,7 +276,6 @@ and sending `%g %nuke`.
281276
282277XX 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
283278
284−<span id="dns"></span>
285279### Appendix A: DNS
286280
287281The `*.urbit.org` domain can be used to access destroyers and cruisers. In the
@@ -350,7 +344,6 @@ When a new version of a page becomes available, it is useful to propagate it to
350344- `/~/on/[hash].json` retuns `true` when a page may require updating.
351345- `/~/on/[hash].js` is a lightweight script that polls for the above. It is primarily used in error messages.
352346
353−<span id="auth"></span>
354347### 1.3 Authentication
355348
356349Authenticated requests are accomplished through sessions, tracked with cookies which are set on the first such request.
@@ -376,10 +369,8 @@ So far, all the paths specified have been GET requests. Authentication, however,
376369- `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`.
377370- `POST {oryx, wire, xyro} /~/to/<ship>/[app]/[mark].json` is a foreign message send, as above.
378371
379−<span id="subs"></span>
380372### 1.5 Subscriptions
381373
382−<span id="of-ixor"></span>
383374- `/~/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.
384375 + `/~/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)
385376- `/~/in/[hash].json` is a dual to [`/~/on`](#on-change). It binds `mod` events, which echo the requesting token.
@@ -387,14 +378,12 @@ So far, all the paths specified have been GET requests. Authentication, however,
387378
388379
389380
390−<span id="temp"></span>
391381### 1.6 Ablative
392382
393383These interfaces will temporarily exist to aid development, and are to be considered unstable.
394384- `/~/debug/...` access normally inaccessible pages. For example, `/~/debug/as.html` will present the login page, regardless of current session status.
395385
396386
397−<span id="client"></span>
398387## 2. Client state
399388
400389Some information is stored on, and provided to, browser clients
@@ -403,7 +392,6 @@ Some information is stored on, and provided to, browser clients
403392
404393Authenticated users receive a cookie on the domain of `*.urbit.org`. The cookie contains a client session token, keyed by the serving ship.
405394
406−<span id="auth-json"></span>
407395### 2.2 Authentication
408396
409397It is common(e.g. by the `%urb` mark) to set window.urb to the contents of `/~/auth.json`:
@@ -422,7 +410,6 @@ To this object, `/main/lib/urb.js` adds helpers:
422410- `drop({path,app?=urb.app}, cb?)` pulls the subscription
423411- `util` is an object containing methods for converting between JavaScript types and Hoon atom odors.
424412
425−<span id="kiss"></span>
426413## 3. Requests
427414
428415## `[%born port=@ud]`, unix init
@@ -485,22 +472,17 @@ Sometimes, messages are received from other ships. They are expected to take the
485472
486473**Gifts given in response:** [`%nice` or `%mean`](#ack).
487474
488−<span id="gram"></span>
489475#### 3.4.1 `gram`
490476
491−<span id="foreign"></span>
492477There are three messages of note, all concerning authentication
493−<span id="lon"></span>
494478- `[/lon ses]` is a login request, which contains the session wishing to authenticate.
495479- 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.
496480- 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.
497481
498482**Gifts given in response:** nice?
499483
500−<span id="gift"></span>
501484## 4. Responses
502485
503−<span id="ack"></span>
504486### 4.1 `[%nice ~]`, `[%mean ares]`, network acknowledgement
505487
506488A `%nice` is given upon receiving an [ames message](#gram), indicating succesful receipt. `%mean` is currently unused directly, but reserved for error conditions.
@@ -516,30 +498,23 @@ Most requests are served with one coherent response, consisting of
516498- `q=mess`, response headers
517499- `r=(unit octs)`, an optional body
518500
519−<span id="that"></span>
520501### 4.3 `[%that httr]`, partial HTTP response
521502
522503[EventStream responses](#of-ixor) consist of multiple sequential chunks. Treated as `%thou`, except the request is kept open.
523504
524−<span id="thar"></span>
525505### 4.4 `[%thar (unit octs)]`, partial HTTP body
526506
527507Complementing `%that`, `%thar` is a body chunk, containing an event. An empty `%thar` signals for the connection to be closed.
528508
529509Body chunks, besides `[1 '\0a']`(a heartbeat newline), are encoded from `even` events. The stem becomes the [`event` field](#eventsource), and the content, `data` lines.
530510
531−<span id="even"></span>
532511#### 4.4.1 `even`, event types
533512
534513There are three events that a [client subscription](#subs) will be given.
535514
536−<span id="even-news"></span>
537515- `[%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.
540516- `[%mean [term path] ares]` is a sourced subscription error.
541517
542−<span id="note"></span>
543518## 5. Vane requests
544519
545520### 5.1 ``[%a %wont sock `[path *]`gram]``, outbound message
@@ -548,15 +523,12 @@ The `%a` interface provides conveyance of [messages](#gram) over UDP.
548523
549524Signs a `%woot` upon message arrival.
550525
551−<span id="wait"></span>
552−### 5.2 `[%b ?(%wait %rest) time]`, timeout set/unset
553526
554527All 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.
555528The `%b` timer interface is used to schedule the next such event, or cancel past scheduled ones when a connection closes.
556529
557530Signs a `%wake` upon timer activation.
558531
559−<span id="wasp"></span>
560532### 5.3 `[%f %wasp @uvI]`, dependency listen
561533
562534Knowledge 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`.
@@ -578,7 +550,6 @@ The simplest functional request is the construction of a page. Saved as a [live]
578550- A `beam`(path in `%clay`) is decoded from the request path.
579551- A `/web/<nyp ced quy>` virtual path is appended, span-encoding method, auth, and query string.
580552
581−<span id="done"></span>
582553### `[%cast mark %done ~ cage]`, convert
583554
584555This is used when communicating with apps, in both directions.
@@ -589,14 +560,12 @@ This is used when communicating with apps, in both directions.
589560
590561The 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.
591562
592−<span id="mess"></span>
593563### `[%mess hapt ship cage]`, app message
594564
595565After 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.
596566
597567Signs a `%nice` or `%mean`, in userspace or upon crashing.
598568
599−<span id="show"></span>
600569### `[%show hapt ship path]`, app subscription
601570
602571An `/~/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`.
@@ -615,17 +584,14 @@ An `/~/is` DELETE is used to remove a subscription, and is converted straightfor
615584
616585Signs an empty `%mean` for each open subscription that is closed.
617586
618−<span id="whir"></span>
619587## 6. In-flight metadata
620588
621589Various state can be associated with requests, but not necessarily be returned in responses to them.
622590
623−<span id="wire-drop"></span>
624591### 6.1 `~`, dropthrough
625592
626593If the response should be sent statelessly further up the duct, the `wire` is empty. This is used in `%f` pure functional page generation.
627594
628−<span id="wire-live"></span>
629595### 6.2 `[?(%y %n) ...]`, stability
630596
631597The first element of a [`%b` timer](#wait) path distinguishes between live(%y) and dying(%n) channels.
@@ -638,17 +604,14 @@ Designates which stream to act upon. Present on `%b` timer cards.
638604
639605Present on `%f` dependency news. Looked up in [the state](#bolo) to see if any response is necessary.
640606
641−<span id="wire-to"></span>
642607### 6.5 `/to/<hasp>/<ship>`, app
643608
644609Present on `%f` translations of message marks
645610
646−<span id="wire-is"></span>
647611### 6.6 `/is/[ixor]/{hasp path}`, subscription
648612
649613Subscription requests. Present on `%g` subscription requests, and `%f` translations of [`%rush` subscription data](#show).
650614
651−<span id="sign"></span>
652615## 7. Vane responses
653616
654617The goal of requests is to cause some manner of result. Specifically,
@@ -685,14 +648,12 @@ The former is [served](#mime) back to the requester(i.e. the remaining duct), an
685648
686649A `%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.
687650
688−<span id="bolo"></span>
689651## 8. Server state
690652
691653There is a quantity of data that persists between events.
692654
693655### 8.1 Global
694656
695−<span id="prefix"></span>
696657- `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`.
697658- `(jar ship hart)` remembered hostnames in order of preference, made accessible through `.^`
698659 + 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]`.
@@ -703,7 +664,6 @@ There is a quantity of data that persists between events.
703664- `(map hole sink)`, session state.
704665- `(map hole ,[ship ?])`, foreign session names, along with their origin ships and whether they are authorized to act on our behalf.
705666
706−<span id="live"></span>
707667### 8.2 `live`, per-request state
708668
709669To honor request cancellations, each unserved request must track which effect it is causing.
@@ -712,7 +672,6 @@ To honor request cancellations, each unserved request must track which effect it
712672+ `[%xeno ship]` if this is a proxied request
713673+ `[%poll ixor]` if this is a session long-poll
714674
715−<span id="sink"></span>
716675### 8.3 `sink`, per-session state
717676
718677Each `hole` has associated authentication state.
@@ -721,12 +680,10 @@ Each `hole` has associated authentication state.
721680- `(jug ship ,[path duct])`, authentication `/~/as` requests waiting on foreign ships.
722681- `(set oryx)`, views associated with this session. Dual of `hole` in `stem`.
723682
724−<span id="stem"></span>
725683### 8.4 `stem`, per-view state
726684
727685Each `oryx` has active subscription state.
728686- `hole`, session in which this view resides. Dual of `(set oryx)` in `sink`.
729−<span id="ixor"></span>
730687- `ixor`, a cached hash of the `oryx` that is used as a subscription id, by the `/~/of` EventStream.
731688- `[,@u (map ,@u even)]`, queued [events](#even). Has a maximum size.
732689- `(unit ,[duct @u ?])`, http connection, its last received event, and whether it is a long-poll request.
@@ -737,14 +694,10 @@ Each `oryx` has active subscription state.
737694## Appendix A: Glossary
738695
739696- An `oryx` is a CSRF token used for [authenticated requests](#auth)
740−<span id="mean-json"></span>
741697- `mean.json` is a rendering of hoon `ares`: an error message formatted as `{fail:'type',mess:"Error message"}`
742−<span id="urb-js"></span>
743698- `urb.js` is the standard client-side implementation of the `%eyre` protocols, normally found in `/=main=/lib`
744−<span id="mime"></span>
745699- 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).
746700
747−<span id="eventsource"></span>
748701## Appendix B: EventSource
749702
750703UNIMPLEMENTED