@@ -47,7 +47,6 @@ Runtime
47Let us follow the loading of a simple cli app, as it bounces from
47Let us follow the loading of a simple cli app, as it bounces from
48browser to server to browser and back.
48browser to server to browser and back.
50−<span id="init"></span>
51### Initial request
50### Initial request
53An http request for `http://sampel-sipnym.urbit.org/cli` will be [redirected](dns)
52An 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
183serves a fresh `auth.json` which reflects the changed `user`. Upon receiving
182serves a fresh `auth.json` which reflects the changed `user`. Upon receiving
184this, the page is refreshed to retry the original request.
183this, the page is refreshed to retry the original request.
186−<span id="auth-ok"></span>
187### Post-authentication: app communication.
185### Post-authentication: app communication.
189Upon refresh, `/~~/cli` brings us for the third time to `%get:process-auth`, but
187Upon 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
207`++add-subs:ix`, the ix core fetched `++for-view` by hashing the request
205`++add-subs:ix`, the ix core fetched `++for-view` by hashing the request
208`++oryx-to-ixor`.
206`++oryx-to-ixor`.
210−<span id="view-ixor"></span>
211A view has all the state associated with a client that must be
208A view has all the state associated with a client that must be
212remembered between events. In this case, this is what app/path the request duct
209remembered between events. In this case, this is what app/path the request duct
213is associated with; but mainly, `++add-subs:ix` will `pass-note` to `%gall` so
210is 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
242either case, eventually a `%mean` or `%nice` arrives, is encoded as json, and
239either case, eventually a `%mean` or `%nice` arrives, is encoded as json, and
243sent to the client callback.
240sent to the client callback.
245−<span id="mage"></span>
246## A path not taken: magic filenames
242## A path not taken: magic filenames
248The `/robots.txt` and `/favicon.(ico|png)` files are static, and served
244The `/robots.txt` and `/favicon.(ico|png)` files are static, and served
@@ -250,7 +246,6 @@ immediately when caught by a `++parse`.
251XX index.html?
247XX index.html?
253−<span id="xeno"></span>
254## A path not taken: foreign auth
249## A path not taken: foreign auth
256While this example details a login `/~/as/own`, it is possible to be
251While this example details a login `/~/as/own`, it is possible to be
@@ -281,7 +276,6 @@ and sending `%g %nuke`.
282XX 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
277XX 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
284−<span id="dns"></span>
285### Appendix A: DNS
279### Appendix A: DNS
287The `*.urbit.org` domain can be used to access destroyers and cruisers. In the
281The `*.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
350- `/~/on/[hash].json` retuns `true` when a page may require updating.
344- `/~/on/[hash].json` retuns `true` when a page may require updating.
351- `/~/on/[hash].js` is a lightweight script that polls for the above. It is primarily used in error messages.
345- `/~/on/[hash].js` is a lightweight script that polls for the above. It is primarily used in error messages.
353−<span id="auth"></span>
354### 1.3 Authentication
347### 1.3 Authentication
356Authenticated requests are accomplished through sessions, tracked with cookies which are set on the first such request.
349Authenticated 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,
376- `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`.
369- `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`.
377- `POST {oryx, wire, xyro} /~/to/<ship>/[app]/[mark].json` is a foreign message send, as above.
370- `POST {oryx, wire, xyro} /~/to/<ship>/[app]/[mark].json` is a foreign message send, as above.
379−<span id="subs"></span>
380### 1.5 Subscriptions
372### 1.5 Subscriptions
382−<span id="of-ixor"></span>
383- `/~/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.
374- `/~/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.
384 + `/~/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)
375 + `/~/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)
385- `/~/in/[hash].json` is a dual to [`/~/on`](#on-change). It binds `mod` events, which echo the requesting token.
376- `/~/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,
390−<span id="temp"></span>
391### 1.6 Ablative
381### 1.6 Ablative
393These interfaces will temporarily exist to aid development, and are to be considered unstable.
383These interfaces will temporarily exist to aid development, and are to be considered unstable.
394- `/~/debug/...` access normally inaccessible pages. For example, `/~/debug/as.html` will present the login page, regardless of current session status.
384- `/~/debug/...` access normally inaccessible pages. For example, `/~/debug/as.html` will present the login page, regardless of current session status.
397−<span id="client"></span>
398## 2. Client state
387## 2. Client state
400Some information is stored on, and provided to, browser clients
389Some information is stored on, and provided to, browser clients
@@ -403,7 +392,6 @@ Some information is stored on, and provided to, browser clients
404Authenticated users receive a cookie on the domain of `*.urbit.org`. The cookie contains a client session token, keyed by the serving ship.
393Authenticated users receive a cookie on the domain of `*.urbit.org`. The cookie contains a client session token, keyed by the serving ship.
406−<span id="auth-json"></span>
407### 2.2 Authentication
395### 2.2 Authentication
409It is common(e.g. by the `%urb` mark) to set window.urb to the contents of `/~/auth.json`:
397It 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:
422- `drop({path,app?=urb.app}, cb?)` pulls the subscription
410- `drop({path,app?=urb.app}, cb?)` pulls the subscription
423- `util` is an object containing methods for converting between JavaScript types and Hoon atom odors.
411- `util` is an object containing methods for converting between JavaScript types and Hoon atom odors.
425−<span id="kiss"></span>
426## 3. Requests
413## 3. Requests
428## `[%born port=@ud]`, unix init
415## `[%born port=@ud]`, unix init
@@ -485,22 +472,17 @@ Sometimes, messages are received from other ships. They are expected to take the
486**Gifts given in response:** [`%nice` or `%mean`](#ack).
473**Gifts given in response:** [`%nice` or `%mean`](#ack).
488−<span id="gram"></span>
489#### 3.4.1 `gram`
475#### 3.4.1 `gram`
491−<span id="foreign"></span>
492There are three messages of note, all concerning authentication
477There 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.
478- `[/lon ses]` is a login request, which contains the session wishing to authenticate.
495- 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.
479- 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.
496- 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.
480- 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.
498**Gifts given in response:** nice?
482**Gifts given in response:** nice?
500−<span id="gift"></span>
501## 4. Responses
484## 4. Responses
503−<span id="ack"></span>
504### 4.1 `[%nice ~]`, `[%mean ares]`, network acknowledgement
486### 4.1 `[%nice ~]`, `[%mean ares]`, network acknowledgement
506A `%nice` is given upon receiving an [ames message](#gram), indicating succesful receipt. `%mean` is currently unused directly, but reserved for error conditions.
488A `%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
516- `q=mess`, response headers
498- `q=mess`, response headers
517- `r=(unit octs)`, an optional body
499- `r=(unit octs)`, an optional body
519−<span id="that"></span>
520### 4.3 `[%that httr]`, partial HTTP response
501### 4.3 `[%that httr]`, partial HTTP response
522[EventStream responses](#of-ixor) consist of multiple sequential chunks. Treated as `%thou`, except the request is kept open.
503[EventStream responses](#of-ixor) consist of multiple sequential chunks. Treated as `%thou`, except the request is kept open.
524−<span id="thar"></span>
525### 4.4 `[%thar (unit octs)]`, partial HTTP body
505### 4.4 `[%thar (unit octs)]`, partial HTTP body
527Complementing `%that`, `%thar` is a body chunk, containing an event. An empty `%thar` signals for the connection to be closed.
507Complementing `%that`, `%thar` is a body chunk, containing an event. An empty `%thar` signals for the connection to be closed.
529Body chunks, besides `[1 '\0a']`(a heartbeat newline), are encoded from `even` events. The stem becomes the [`event` field](#eventsource), and the content, `data` lines.
509Body chunks, besides `[1 '\0a']`(a heartbeat newline), are encoded from `even` events. The stem becomes the [`event` field](#eventsource), and the content, `data` lines.
531−<span id="even"></span>
532#### 4.4.1 `even`, event types
511#### 4.4.1 `even`, event types
534There are three events that a [client subscription](#subs) will be given.
513There are three events that a [client subscription](#subs) will be given.
536−<span id="even-news"></span>
537- `[%news hash]` is a `%f` update, and contains the relevant dependency token.
515- `[%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.
540- `[%mean [term path] ares]` is a sourced subscription error.
516- `[%mean [term path] ares]` is a sourced subscription error.
542−<span id="note"></span>
543## 5. Vane requests
518## 5. Vane requests
545### 5.1 ``[%a %wont sock `[path *]`gram]``, outbound message
520### 5.1 ``[%a %wont sock `[path *]`gram]``, outbound message
@@ -548,15 +523,12 @@ The `%a` interface provides conveyance of [messages](#gram) over UDP.
549Signs a `%woot` upon message arrival.
524Signs a `%woot` upon message arrival.
551−<span id="wait"></span>
552−### 5.2 `[%b ?(%wait %rest) time]`, timeout set/unset
554All 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.
527All 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.
555The `%b` timer interface is used to schedule the next such event, or cancel past scheduled ones when a connection closes.
528The `%b` timer interface is used to schedule the next such event, or cancel past scheduled ones when a connection closes.
557Signs a `%wake` upon timer activation.
530Signs a `%wake` upon timer activation.
559−<span id="wasp"></span>
560### 5.3 `[%f %wasp @uvI]`, dependency listen
532### 5.3 `[%f %wasp @uvI]`, dependency listen
562Knowledge 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`.
534Knowledge 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]
578- A `beam`(path in `%clay`) is decoded from the request path.
550- A `beam`(path in `%clay`) is decoded from the request path.
579- A `/web/<nyp ced quy>` virtual path is appended, span-encoding method, auth, and query string.
551- A `/web/<nyp ced quy>` virtual path is appended, span-encoding method, auth, and query string.
581−<span id="done"></span>
582### `[%cast mark %done ~ cage]`, convert
553### `[%cast mark %done ~ cage]`, convert
584This is used when communicating with apps, in both directions.
555This is used when communicating with apps, in both directions.
@@ -589,14 +560,12 @@ This is used when communicating with apps, in both directions.
590The 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.
561The 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.
592−<span id="mess"></span>
593### `[%mess hapt ship cage]`, app message
563### `[%mess hapt ship cage]`, app message
595After 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.
565After 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.
597Signs a `%nice` or `%mean`, in userspace or upon crashing.
567Signs a `%nice` or `%mean`, in userspace or upon crashing.
599−<span id="show"></span>
600### `[%show hapt ship path]`, app subscription
569### `[%show hapt ship path]`, app subscription
602An `/~/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`.
571An `/~/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
616Signs an empty `%mean` for each open subscription that is closed.
585Signs an empty `%mean` for each open subscription that is closed.
618−<span id="whir"></span>
619## 6. In-flight metadata
587## 6. In-flight metadata
621Various state can be associated with requests, but not necessarily be returned in responses to them.
589Various state can be associated with requests, but not necessarily be returned in responses to them.
623−<span id="wire-drop"></span>
624### 6.1 `~`, dropthrough
591### 6.1 `~`, dropthrough
626If the response should be sent statelessly further up the duct, the `wire` is empty. This is used in `%f` pure functional page generation.
593If the response should be sent statelessly further up the duct, the `wire` is empty. This is used in `%f` pure functional page generation.
628−<span id="wire-live"></span>
629### 6.2 `[?(%y %n) ...]`, stability
595### 6.2 `[?(%y %n) ...]`, stability
631The first element of a [`%b` timer](#wait) path distinguishes between live(%y) and dying(%n) channels.
597The 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.
639Present on `%f` dependency news. Looked up in [the state](#bolo) to see if any response is necessary.
605Present on `%f` dependency news. Looked up in [the state](#bolo) to see if any response is necessary.
641−<span id="wire-to"></span>
642### 6.5 `/to/<hasp>/<ship>`, app
607### 6.5 `/to/<hasp>/<ship>`, app
644Present on `%f` translations of message marks
609Present on `%f` translations of message marks
646−<span id="wire-is"></span>
647### 6.6 `/is/[ixor]/{hasp path}`, subscription
611### 6.6 `/is/[ixor]/{hasp path}`, subscription
649Subscription requests. Present on `%g` subscription requests, and `%f` translations of [`%rush` subscription data](#show).
613Subscription requests. Present on `%g` subscription requests, and `%f` translations of [`%rush` subscription data](#show).
651−<span id="sign"></span>
652## 7. Vane responses
615## 7. Vane responses
654The goal of requests is to cause some manner of result. Specifically,
617The 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
686A `%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.
649A `%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.
688−<span id="bolo"></span>
689## 8. Server state
651## 8. Server state
691There is a quantity of data that persists between events.
653There is a quantity of data that persists between events.
693### 8.1 Global
655### 8.1 Global
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`.
657- `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`.
697- `(jar ship hart)` remembered hostnames in order of preference, made accessible through `.^`
658- `(jar ship hart)` remembered hostnames in order of preference, made accessible through `.^`
698 + 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]`.
659 + 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.
703- `(map hole sink)`, session state.
664- `(map hole sink)`, session state.
704- `(map hole ,[ship ?])`, foreign session names, along with their origin ships and whether they are authorized to act on our behalf.
665- `(map hole ,[ship ?])`, foreign session names, along with their origin ships and whether they are authorized to act on our behalf.
706−<span id="live"></span>
707### 8.2 `live`, per-request state
667### 8.2 `live`, per-request state
709To honor request cancellations, each unserved request must track which effect it is causing.
669To 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
712+ `[%xeno ship]` if this is a proxied request
672+ `[%xeno ship]` if this is a proxied request
713+ `[%poll ixor]` if this is a session long-poll
673+ `[%poll ixor]` if this is a session long-poll
715−<span id="sink"></span>
716### 8.3 `sink`, per-session state
675### 8.3 `sink`, per-session state
718Each `hole` has associated authentication state.
677Each `hole` has associated authentication state.
@@ -721,12 +680,10 @@ Each `hole` has associated authentication state.
721- `(jug ship ,[path duct])`, authentication `/~/as` requests waiting on foreign ships.
680- `(jug ship ,[path duct])`, authentication `/~/as` requests waiting on foreign ships.
722- `(set oryx)`, views associated with this session. Dual of `hole` in `stem`.
681- `(set oryx)`, views associated with this session. Dual of `hole` in `stem`.
724−<span id="stem"></span>
725### 8.4 `stem`, per-view state
683### 8.4 `stem`, per-view state
727Each `oryx` has active subscription state.
685Each `oryx` has active subscription state.
728- `hole`, session in which this view resides. Dual of `(set oryx)` in `sink`.
686- `hole`, session in which this view resides. Dual of `(set oryx)` in `sink`.
729−<span id="ixor"></span>
730- `ixor`, a cached hash of the `oryx` that is used as a subscription id, by the `/~/of` EventStream.
687- `ixor`, a cached hash of the `oryx` that is used as a subscription id, by the `/~/of` EventStream.
731- `[,@u (map ,@u even)]`, queued [events](#even). Has a maximum size.
688- `[,@u (map ,@u even)]`, queued [events](#even). Has a maximum size.
732- `(unit ,[duct @u ?])`, http connection, its last received event, and whether it is a long-poll request.
689- `(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.
737## Appendix A: Glossary
694## Appendix A: Glossary
739- An `oryx` is a CSRF token used for [authenticated requests](#auth)
696- An `oryx` is a CSRF token used for [authenticated requests](#auth)
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"}`
697- `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`
698- `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).
699- 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).
747−<span id="eventsource"></span>
748## Appendix B: EventSource
701## Appendix B: EventSource
750UNIMPLEMENTED
703UNIMPLEMENTED