From 9c4b78ed2f06316baaf5265fc8e21e1886f6f681 Mon Sep 17 00:00:00 2001 From: bonbud-macryg Date: Wed, 10 Jul 2024 16:58:53 +0100 Subject: [PATCH 1/7] Draft behn doc skeleton --- pkg/arvo/neo/cod/std/src/fil/behn.txt | 72 +++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 pkg/arvo/neo/cod/std/src/fil/behn.txt 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..37b9861347 --- /dev/null +++ b/pkg/arvo/neo/cod/std/src/fil/behn.txt @@ -0,0 +1,72 @@ +# 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` + +[Example usage] + From 4f02db3ba92087bd3e9f925c9d12e944cb47cd99 Mon Sep 17 00:00:00 2001 From: bonbud-macryg Date: Thu, 11 Jul 2024 16:11:25 +0100 Subject: [PATCH 2/7] Document %wake --- pkg/arvo/neo/cod/std/src/fil/behn.txt | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/pkg/arvo/neo/cod/std/src/fil/behn.txt b/pkg/arvo/neo/cod/std/src/fil/behn.txt index 37b9861347..d24800eaf3 100644 --- a/pkg/arvo/neo/cod/std/src/fil/behn.txt +++ b/pkg/arvo/neo/cod/std/src/fil/behn.txt @@ -19,7 +19,7 @@ Behn takes one request — to set a timer or cancel one — and gives one resp -- ``` -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 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. @@ -68,5 +68,17 @@ This shrub accepts a poke that cancels a specific timer. We identify the timer t ### `%wake` -[Example usage] +When /app/neo receives a `%wake` task from the Behn vane, it pokes the relevant shrubs with the `%wake` `gift:behn`. +[am i right in thinking shrubs can only start timers on one wire and receive `%wake`s for timers on that same wire?] + +``` +++ 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 ~])] + == +``` From c86679f2000277ecfab3e921865c878483ce0d20 Mon Sep 17 00:00:00 2001 From: bonbud-macryg Date: Fri, 12 Jul 2024 10:55:21 +0100 Subject: [PATCH 3/7] Draft Iris docs --- pkg/arvo/neo/cod/std/src/fil/iris.md | 75 ++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 pkg/arvo/neo/cod/std/src/fil/iris.md 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 + ... + == +``` + From f2df0c4e4576180b6d4b0d2f31c7a02db9f279c0 Mon Sep 17 00:00:00 2001 From: bonbud-macryg Date: Fri, 12 Jul 2024 17:16:41 +0100 Subject: [PATCH 4/7] Draft eyre docs --- pkg/arvo/neo/cod/std/src/fil/eyre.md | 77 ++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 pkg/arvo/neo/cod/std/src/fil/eyre.md 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..dff24a8024 --- /dev/null +++ b/pkg/arvo/neo/cod/std/src/fil/eyre.md @@ -0,0 +1,77 @@ +# 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 + +[looks like it stores state in two diff formats and has a map of bound URLs] + +The Eyre shane stores three things in its state. +- `by-id`: ??? +- `by-pith`: ??? +- `bind`: a map of Eyre [binding](https://docs.urbit.org/system/kernel/eyre/reference/data-types#binding)s to Shrubbery `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` + +??? + +### `%data` + +??? + +### `%done` + +??? + +### `%bound` + +??? From 0e60f5f8b8c7c28b0d4f2504ec740d924202c620 Mon Sep 17 00:00:00 2001 From: bonbud-macryg Date: Thu, 1 Aug 2024 18:10:48 +0100 Subject: [PATCH 5/7] Implement feedback --- pkg/arvo/neo/cod/std/src/fil/behn.txt | 2 -- pkg/arvo/neo/cod/std/src/fil/eyre.md | 16 +++++++--------- 2 files changed, 7 insertions(+), 11 deletions(-) diff --git a/pkg/arvo/neo/cod/std/src/fil/behn.txt b/pkg/arvo/neo/cod/std/src/fil/behn.txt index d24800eaf3..55c352f426 100644 --- a/pkg/arvo/neo/cod/std/src/fil/behn.txt +++ b/pkg/arvo/neo/cod/std/src/fil/behn.txt @@ -70,8 +70,6 @@ This shrub accepts a poke that cancels a specific timer. We identify the timer t When /app/neo receives a `%wake` task from the Behn vane, it pokes the relevant shrubs with the `%wake` `gift:behn`. -[am i right in thinking shrubs can only start timers on one wire and receive `%wake`s for timers on that same wire?] - ``` ++ poke |= [=stud:neo vaz=vase] diff --git a/pkg/arvo/neo/cod/std/src/fil/eyre.md b/pkg/arvo/neo/cod/std/src/fil/eyre.md index dff24a8024..6886045762 100644 --- a/pkg/arvo/neo/cod/std/src/fil/eyre.md +++ b/pkg/arvo/neo/cod/std/src/fil/eyre.md @@ -4,12 +4,10 @@ Eyre is Urbit's HTTP server vane. Shrubbery can use Eyre to serve UIs to your de ## Types -[looks like it stores state in two diff formats and has a map of bound URLs] - The Eyre shane stores three things in its state. -- `by-id`: ??? -- `by-pith`: ??? -- `bind`: a map of Eyre [binding](https://docs.urbit.org/system/kernel/eyre/reference/data-types#binding)s to Shrubbery `pith`s. +- `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 @@ -62,16 +60,16 @@ In the code below, we construct a `req:eyre:neo` by giving it a `binding:eyre` a ### `%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. From 418d4f3ce1d618ea02c94734b294479a98d21799 Mon Sep 17 00:00:00 2001 From: bonbud-macryg Date: Wed, 7 Aug 2024 12:05:36 +0100 Subject: [PATCH 6/7] Draft clay docs --- pkg/arvo/neo/cod/std/src/fil/clay.md | 46 ++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 pkg/arvo/neo/cod/std/src/fil/clay.md 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. From abd19c4e07f73e4a8561f239f5d66171bd45169f Mon Sep 17 00:00:00 2001 From: bonbud-macryg Date: Wed, 7 Aug 2024 13:00:58 +0100 Subject: [PATCH 7/7] Draft Gall docs skeleton --- pkg/arvo/neo/cod/std/src/fil/gall.md | 63 ++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 pkg/arvo/neo/cod/std/src/fil/gall.md 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).