diff --git a/pkg/arvo/neo/cod/std/src/fil/behn.txt b/pkg/arvo/neo/cod/std/src/fil/behn.txt new file mode 100644 index 0000000000..55c352f426 --- /dev/null +++ b/pkg/arvo/neo/cod/std/src/fil/behn.txt @@ -0,0 +1,82 @@ +# Behn + +Behn takes one request — to set a timer or cancel one — and gives one response to say a timer went off. + +``` +++ behn + |% + :: $req: Timer request + :: + :: %wait: Set timer + :: %rest: Cancel timer + :: + +$ req $>(?(%rest %wait) task:^behn) + :: $res: Timer response + :: + :: %wake: Timer went off + :: + +$ res $>(%wake gift:^behn) + -- +``` + +The request is a regular `task:behn`, the code above just filters for `task:behn`s head-tagged with `%rest` and `%wait`. The response is a regular `gift:behn`, but filtered for `%wake` `gift`s. + +The Behn shane itself is just a `(jug @da pith)`, as we see in `/sur/neo.hoon`. This is Shrubbery's conception of Behn's state. + +``` ++$ behn (jug @da pith) +``` + +*** + +## Tasks + +[explain $ pith] + +[explain %behn-req] + +### `%wait` + +In this example, we set a behn timer to go off five seconds after the shrub has been initialized. + +``` +++ init + |= old=(unit pail:neo) + ^- (quip card:neo pail:neo) + :_ old + :~ [#/[p/our.bowl]/$/behn %poke %behn-req !>([%wait (add now.bowl ~5s)])] + == +``` + +### `%rest` + +This shrub accepts a poke that cancels a specific timer. We identify the timer to cancel by passing in the time it was supposed to go off. + +``` +++ poke + |= [=stud:neo vaz=vase] + ^- (quip card:neo pail:neo) + =/ act !<(example-diff vaz) + ?> =(-.act %rest) + :_ state + :: cancel timer that was set to go off at ~2024.7.10..15.0.0 + :~ [#/[p/our.bowl]/$/behn %poke %behn-req !>([%rest ~2024.7.10..15.0.0])] + == +``` + +## Gifts + +### `%wake` + +When /app/neo receives a `%wake` task from the Behn vane, it pokes the relevant shrubs with the `%wake` `gift:behn`. + +``` +++ poke + |= [=stud:neo vaz=vase] + ^- (quip card:neo pail:neo) + =/ act !<(behn-res vaz) + :_ state + :~ [#/[p/our.bowl]/$/behn %poke %example-diff !>([%timeout ~])] + [#/[p/opponent.bowl]/$/behn %poke %example-diff !>([%timeout ~])] + == +``` diff --git a/pkg/arvo/neo/cod/std/src/fil/clay.md b/pkg/arvo/neo/cod/std/src/fil/clay.md new file mode 100644 index 0000000000..dce3a5d661 --- /dev/null +++ b/pkg/arvo/neo/cod/std/src/fil/clay.md @@ -0,0 +1,46 @@ +# Clay + +Clay is Arvo's filesystem vane. Shrubbery uses Clay to track changes in specific files. + +## Types + +The Clay shane stores a map of {pith} to {dk how to word this} in its state. + +``` ++$ clay + (map [src=pith hand=pith] [case=@ud =desk =path as=(unit mark)]) +``` + +The Clay shane takes two requests, one response, and defines a `peer` type for subscriptions. The `peer` is a desk, a path to the file in question in that desk, and optionally a specific mark we'd like to receive updated versions of that file through. + +``` +++ clay + |% + +$ peer [=desk =path as=(unit mark)] + +$ req + $% [%peer =pith =peer] + [%pull =pith] + == + +$ res [=pith case=@ud files=(axol cage)] + -- +``` + +## Tasks + +### `%peer` + +Subscribe to a file at the given `pith`. + +### `%pull` + +Cancel a subscription to a file at the given `pith`. + +## Gifts + +The response from Clay, relayed from Shrubbery to the userspace shrub. + +``` ++$ res [=pith case=@ud files=(axol cage)] +``` + +Contains the `pith` to the relevant directory in Clay, a version number for that directory, and a recursive tree of `cage`s containing the updated files in that directory. diff --git a/pkg/arvo/neo/cod/std/src/fil/eyre.md b/pkg/arvo/neo/cod/std/src/fil/eyre.md new file mode 100644 index 0000000000..6886045762 --- /dev/null +++ b/pkg/arvo/neo/cod/std/src/fil/eyre.md @@ -0,0 +1,75 @@ +# Eyre + +Eyre is Urbit's HTTP server vane. Shrubbery can use Eyre to serve UIs to your device and serve resources of all kinds to the clearweb. + +## Types + +The Eyre shane stores three things in its state. +- `by-id`: Map of HTTP request ID to the pith of the shrub which is handling the request. +- `by-pith`: Map of pith to ID; `by-id` in reverse. +- `bind`: Map of Eyre [binding](https://docs.urbit.org/system/kernel/eyre/reference/data-types#binding)s to `pith`s. + +``` ++$ eyre + $: by-id=(map @ta pith) + by-pith=(map pith @ta) + bind=(map binding:^^eyre pith) + == +``` + +The Eyre shane manages several requests and responses, covered in detail below. + +``` +++ eyre + |% + +$ req [%connect =binding:^eyre =pith] + +$ res [%bound ~] + +$ sign (pair @ta gift) + +$ gift + $% [%head =response-header:http] + [%data dat=(unit octs)] + [%done ~] + == + +$ task + (pair @ta inbound-request:^eyre) + -- +``` + +Note: `task:eyre:neo` is the type of [`inbound-request`](https://docs.urbit.org/system/kernel/eyre/reference/data-types#inbound-request) that comes in via HTTP from the clearweb. You wouldn't send this from a shrub. + +## Tasks + +### `%connect` + +The `%connect` pail is the Eyre shane's version of Eyre's [`%request`](https://docs.urbit.org/system/kernel/eyre/reference/tasks#request) task. It's the only type of `req:eyre:neo`. + +In the code below, we construct a `req:eyre:neo` by giving it a `binding:eyre` and a `pith:neo`. The `binding` corresponds to the subdomain `/neo/sky` (to serve a frontend to `/neo/sky`) and the `pith` is `here.bowl`, the location of this shrub. + +``` +++ init + |= pal=(unit pail:neo) + :_ sig/!>(~) + =/ =pith:neo #/[p/our.bowl]/$/eyre + =/ =binding:eyre [~ ~[%neo %sky]] + =/ =req:eyre:neo [%connect binding here.bowl] + :~ [pith %poke eyre-req/!>(req)] + == +``` + +## Gifts + +### `%head` + +The HTTP header of the response. Has to be given immediately so the connection doesn't time out. + +### `%data` + +The actual data of the HTTP request. + +### `%done` + +HTTP request has finished, the connection has closed. + +### `%bound` + +URL has been successfully bound. diff --git a/pkg/arvo/neo/cod/std/src/fil/gall.md b/pkg/arvo/neo/cod/std/src/fil/gall.md new file mode 100644 index 0000000000..b7e6e1d97a --- /dev/null +++ b/pkg/arvo/neo/cod/std/src/fil/gall.md @@ -0,0 +1,63 @@ +# Gall + +Gall is Arvo's userspace software vane. Shrubbery interfaces with Gall by accepting subscription updates, {what else?}. + +## Types + +??? + +{peer could be subscription, peek is probably a scry?} + +{what is `=< gall` storing?} + +``` +++ gall + =< gall + |% + +$ gall + $: peer=(jug pith pith) + peek=(map pith peek:^^gall) + == + -- +``` + +The Gall shane takes four requests and only gives one response, a `(pair pith sign)` for subscription updates from agents. + +``` +++ gall + |% + +$ req + $% [%peek p=@dr] + [%keep ~] + [%reap ~] + [%peer ~] + == + +$ peek [src=(set pith) refresh=@dr] + +$ sign sign:agent:^gall + +$ res (pair pith sign) + -- +``` + +## Tasks + +### `%peek` + +??? + +### `%keep` + +??? + +### `%reap` + +??? + +### `%peer` + +??? + +## Gifts + +### `(pair pith sign)` + +Subscription update from a Gall agent, in practice usually `%facts`. The `pith` corresponds to the [`wire`](https://docs.urbit.org/courses/app-school/types#wire) and the `sign` the [`sign:agent:gall`](https://docs.urbit.org/system/kernel/gall/reference/data-types#signagent). diff --git a/pkg/arvo/neo/cod/std/src/fil/iris.md b/pkg/arvo/neo/cod/std/src/fil/iris.md new file mode 100644 index 0000000000..4f9d740faa --- /dev/null +++ b/pkg/arvo/neo/cod/std/src/fil/iris.md @@ -0,0 +1,75 @@ +# Iris + +[Iris](https://docs.urbit.org/system/kernel/iris) is the HTTP client vane, used to fetch resources from the web. + +## Types + +The Iris shane takes one request (`res`) and one response (`req`). + +``` +++ iris + |% + +$ req [hand=pith dat=request:http] + +$ res [hand=pith dat=request:http] + -- +``` + +In both types the `hand` is "the wire" as far as Shrubbery is concerned, and `dat` is Eyre's `request:http`. + +## Tasks + +### `%request` + +Iris' [`%request`](https://docs.urbit.org/system/kernel/iris/reference/tasks#request) task fetches a remote HTTP resource. You can send this task in Shrubbery through the `%iris-req` poke. + +``` +++ poke + |= [=stud:neo vax=vase] + ^- (quip card:neo pail:neo) + =+ !<(keys=@t q.pail) + ?+ stud !! + ... + %openapi-req + =+ !<(=req:openai vax) + ?> ?=(%chat-create -.q.req) + :_ [%txt !>(keys)] + =/ =request:http + :* %'POST' + 'https://api.openai.com/v1/chat/completions' + (headers:openai keys) + `(as-octt:mimes:html (trip (en:json:html (chat-create-req:enjs:openai +.q.req)))) + == + ~& [%req request] + =/ =req:iris:neo [#/foo request] + :~ [#/[p/our.bowl]/$/iris %poke [%iris-req !>(req)]] + == + == +``` + +## Gifts + +### `%http-response` + +When Eyre receives the HTTP resource, it sends Shrubbery a [`client-response`](https://docs.urbit.org/system/kernel/iris/reference/data-types#client-response) head-tagged with `%finished`. This response contains the `hand` pith specified in the request, so once you've routed to the `%iris-res` pail you could further route on the `hand` to handle more than one kind of HTTP response. + +``` +++ poke + |= [=stud:neo vax=vase] + ^- (quip card:neo pail:neo) + =+ !<(keys=@t q.pail) + ?+ stud !! + %iris-res + =+ !<(=res:iris:neo vax) + ?. ?=(%finished -.dat.res) + `pail + ?~ full-file.dat.res + `pail + =/ body=cord q.data.u.full-file.dat.res + =/ jon=json (need (de:json:html body)) + ~& [%jon jon] + ~& [%result (chat-completion-res:dejs:openai jon)] + `pail + ... + == +``` +