Document shanes

pkg/arvo/neo/cod/std/src/fil/behn.txt

@@ -0,0 +1,84 @@
+# 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`.
+
+[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 ~])]
+  ==
+```

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 `<localhost:port>/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`
+
+???

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
+    ...
+  ==
+```
+