urbit/shrub
1
1
Fork 0
mirror of https://github.com/urbit/shrub.git synced 2024-12-15 12:43:31 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'dillbo' of https://github.com/urbit/urbit into dillbo

Browse Source
This commit is contained in:
C. Guy Yarvin 2015-04-01 14:03:40 -07:00
commit 28e1bf1a71
1 changed files with 113 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

129
docs/pub/doc/arvo/eyre/commentary.md
View File

@ -6,12 +6,12 @@ todo
Eyre: Commentary
================
Let us follow the loading of a simple tic tac toe app, as it bounces from
Let us follow the loading of a simple cli app, as it bounces from
browser to server to browser and back.
## Initial request
## Initial request[#init]
An http request for `http://sampel-sipnym.urbit.org/tic` will be [redirected](dns)
An http request for `http://sampel-sipnym.urbit.org/cli` will be [redirected](dns)
to the `%eyre` on ~sampel-sipnym, and come in as a `%this` kiss.
From arvo, requests enter `++call`, which after some type reification are passed
@ -28,12 +28,12 @@ request, and if this does not make the response immediately obvious,
`++parse` produces the `perk`, by attempting to interpret the `pork`(url path)
[`++as-magic-filename`](#mage), `++as-beam`, and `++as-aux-request`. In this
case, `/tic` is parsed by the second case as a `%beam` query to `/=tic=`: a path
case, `/cli` is parsed by the second case as a `%beam` query to `/=cli=`: a path
which starts with a valid ship name is expected to be a full clay(well, ford)
path, and one starting with a term implies the current serving ship and a case
of `0`, the current revision.
XX spur: when the desks are merged, `/tic` shall point to `/=main=/pub/tic`
XX spur: when the desks are merged, `/cli` shall point to `/=main=/pub/cli`
The parsed `perk` generates a `%for` pest, `mark`ed as its extension(here
defaulting to `%urb`) and `wire`d with `~` to return unaltered to the client. It
@ -41,8 +41,8 @@ goes on to `++resolve` by being passed to `++ford-get-beam`, which translates
the perk it into a `%f %exec %boil` note, adding an fcgi path-segment containing
query string and auth information.
`%ford`s translation of `/=tic=/hymn/hook` to a self-refreshing `%urb` html page
[deserves its own commentary](../../ford/commentary), but we resume in `%eyre`
`%ford`s translation of `/=cli=/hymn/hook` to a self-refreshing `%urb` html page
[deserves its own commentary](../ford/commentary), but we resume in `%eyre`
when the `%made` sign arrives in `++take`, and soon after `++axon:ye`. There the
`wire`, or rather the `whir` it has been verified to be, determines that the
response should be served immediately. However, as the mark is not `%mime`,
@ -60,7 +60,7 @@ is a ford-readable hash of the set of resources that page construction depended
on.
This triggers another `%this` request. Its handling is identical to that of
`/tic` up until `++parse`, where it is seen not `++as-beam` but
`/cli` up until `++parse`, where it is seen not `++as-beam` but
`++as-aux-request`(auxillary requests starting with `/~/` or `/~~/`).
`/on/[hash]` is a long-`%poll`, which `++process-parsed`, for a `.js` mark,
answers with a direct `%fin %js`. Its contents are the static `++poll:js`, which
@ -71,9 +71,112 @@ A `%fin` `perk` is `resolve`d by `resolve-fin`, which serves `%js` as a
`text/javascript` success `%this`.
When `poll.js` is recieved by the client, it opens an `XMLHttpRequest` for
`/~/on/{window.urb.poll}.json`, bringing us back to `%poll:++process`.
`/~/on/{window.urb.poll}.json`, bringing us back to `%poll:process`.
In the case of a non-`%js` `/~/on/`, `++process-parsed`
In the case of a non-`%js` `/~/on/`, `%poll:process-parsed` turns into a
`++new-dependency`, which stores the listening duct, and `pass-note`s a `%wasp`
with the deps-hash back to `%ford` whence it came. While this occured, the page
has loaded.
Some indeterminate amount of time afterwards, with dropped `/~/on/{...}.json`s
being retried upon expiring and also being stored, a `%news` sign arrives in
`++axon`, and the hash in question is retrieved from the wire, and the listening
long-polls retrieved by the hash. Each receives a 205 "Reload parent view" HTTP
response, which `poll.js` dutifully executes, and a fixed typo of markdown is
rendered.
## Authentication.
Now, while this accurately reflects the presentation of e.g. a markdown file,
`/cli` is an application front-end, and one that permits only owner access. Its
second script is `@"/~~/~/at/main/lib/urb.js"`, semantically equivalent to
`/~/as/own/~/at/main/lib/urb.js`, and handled as follows.
In `++as-aux-request`, `%as %own` becomes `%auth %get our` perk, which
`++process` passes to `++process-parsed` passes to `++process-auth`. There, a
`yac` "ya" core is built `++for-client`: a `++cookie-prefix`, which is just the
serving ship name, is used to get a `++session-from-cookies`, here nil as the
client has no cookie set. In lieu of a cookie, a `++new-ya` is constructed, with
a random token `hole` and a `++new-cyst` which fills out `cyst` session state
from request data.
Returning to `++process-auth`, `%get` checks if the yac is authenticated with
the requested credentials(anonymous requests are always granted), which for the
fresh new `cyst` is not the case (more on success [later](#auth-ok)). Unless
authentiacting as a [foreign ship](#xeno), the only thing left is to
`++show-login-page`, which detects that the requested resource is not `%html`,
and produces a `%red` pest. For `%js`, `%red`irections `++resolve` to
`auth-redir:js`, a line of javascript which prepends `/~~` to the url path.
The owner-authenticated main page request similarly ends in `++show-login-page`,
which for the empty session `%fin`ishes with 401("unauthorized")
`++login-page:xml`.
The login page shows a simple prompt, and requests `/~/at/auth.js` to handle the
submission. And so we are, once again, attempting to divine if what we're doing
makes sense `++as-aux-request`.
To understand `/~/at`, there will first be a brief diversion to `~/auth.json`.
`auth.json`, perk `[%auth %json]`, in `++process-auth` serves `++stat-json:ya`,
containing such information as the serving ship, which identities are associated
with this session, and `oryx`, a CSRF token. The latter must be present on all
stateful requests, in this case needed to execute a log in.
`/~/at` is an alternate interface, which injects `auth.json` data into the
requested file. `/~/at/auth.js`, then, is a request for the built-in `auth:js`
(parsed to and processed from an `[%auth %js ~]` perk), with session data added
as `window.urb`. And indeed, ``[`%js /~/at/auth]`` is parsed to
``[%auth at [`%js /auth]``, which in `++process-auth` is re-`process`ed to
`[%fin %js {static script}]`, which is `++resolve-fin` after an `++add-json` of
the relevant data. (immediate resolution is necessary to preserve any `..ya`
state change effected by `++auth-json:ya`.
It is at this point that there is first occasion for user input, namely the password.
The `auth:js` script sends a `PUT` request, also to `/~/auth.json`, which is
parsed to a `[%auth %try {password}]` perk, and upon success produces an updated
`auth.json` which reflects the changed `user`. Upon recieving this, the page is
refreshed to retry the original request.
## Authentication: success. [#auth-ok]
Upon refresh, `/~~/cli` brings us for the third time to `%get:process-auth`, but
this time the cookie is set, and the `yac` fetched contains the serving ship as
authenticated. The `++handle` sample is updated to reflect the requesting ship,
and the `process` continues for the rest of the pork, once again serving the
ford page.
The `/~/on/[deps].json` poll starts anew, and `/~~/~/at/main/lib/urb.js` we now
know to serve the window.urb necessary to make requests, and the sandard library
which extends it with a number of wrappers to them and other useful functions.
One of those functions is `urb.bind`, which is used to subscribe to application data.
Userspace javascript sets `urb.appl` to `/tic`, and binds XXX
## A path not taken: magic filenames [#mage]
The `/robots.txt` and `/favicon.(ico|png)` files are static, and served
immediately when caught by a `++parse`.
XX index.html?
## A path not taken: foreign auth [#xeno]
While this example details a login `/~/as/own`, it is possible to be
authenticated as any ship on the network. A request for such seen in `%get:
process-auth` is passed to `++foreign-auth:ya`, which sends an `%ames /lon`
message to the ship in question. The foreign ship stores the inquiry a responds
with a `/hat`, containing the redirection host; this host is used to send the
client to a `/~/am` url on the foreign client, which acts as a normal login page
but later sends the client back. XX expand, basically the status quo is you're
logged in and `/~/as/foo` is ignored, just setting your `urb.user` XX
## A path not taken: deauthentication
`/~/away`, perk `[%away ~]`, produces a static `++logout-page:xml`, which also
uses `/~/at/auth.js`, to send a `DELETE /~/auth.json`, perk `[%auth %del]`. This
wipes the session from memory.
## Appendix A: DNS [#dns]
@ -83,9 +186,3 @@ instance. We do not speak of the uncommon case. When ports are blocked and
infrastructure crumbles around you, only imported martian networking can be
trusted: the `%get` and `%got` [gram]()s are used to proxy [`%this` requests]() and
[`%thou` responses]() respectively.
## Appendix B: magic filenames [#mage]
The `/robots.txt` and `/favicon.(ico|png)` files are static, and served immediately when caught by a `++parse`.
XX index.html?