@@ -7,6 +7,7 @@ template = "doc.html"
77# Contents
88
99- [Introduction](#introduction)
10+- [Authenticating](#authenticating)
1011- [Using the Channel System](#using-the-channel-system)
1112- [Scrying](#scrying)
1213- [Running Threads With Spider](#running-threads-with-spider)
@@ -20,11 +21,11 @@ This documents contains practical examples of the various ways of interacting wi
2021
2122General documentation of the `task`s and methods described here are available in the [External API Reference](@/docs/arvo/eyre/external-api-ref.md) document and the [Internal API Reference](@/docs/arvo/eyre/tasks.md) document.
2223
23−# Using The Channel System
24+# Authenticating
2425
25−Here we'll look at a practical example of Eyre's channel system. You can refer to the [Channels](@/docs/arvo/eyre/external-api-ref.md#channels) section of the [External API Reference](@/docs/arvo/eyre/external-api-ref.md) document for relevant details.
26+In most cases we must obtain a valid session cookie by [authenticating](@/docs/arvo/eyre/external-api-ref.md#authentication) with our web login code (which can be obtained by running `+code` in the dojo) before we can use Eyre's interfaces (such as the channel system or scry interface).
2627
27−The first thing we need to do is obtain a session cookie by [authenticating](@/docs/arvo/eyre/external-api-ref.md#authentication) with our web login code, which you can get by running `+code` in the dojo. In our case we'll just use the default code for a fakezod.
28+Here we'll try authenticating with the default fakezod code.
2829
2930Using `curl` in the unix terminal, we'll make an HTTP POST request with `"password=<code>"` in the body:
3031
@@ -42,6 +43,14 @@ Server: urbit/vere-1.5
4243set-cookie: urbauth-~zod=0v3.j2062.1prp1.qne4e.goq3h.ksudm; Path=/; Max-Age=604800
4344```
4445
46+The `urbauth-....` cookie can be now be included in subsequent requests (e.g. to the channel system) by providing it in a Cookie HTTP header.
47+
48+# Using The Channel System
49+
50+Here we'll look at a practical example of Eyre's channel system. You can refer to the [Channels](@/docs/arvo/eyre/external-api-ref.md#channels) section of the [External API Reference](@/docs/arvo/eyre/external-api-ref.md) document for relevant details.
51+
52+First, we must obtain a session cookie by [authenticating](#authenticating).
53+
4554Now that we have our cookie, we can try poking an app & simultaneously opening a new channel. In this case, we'll poke the `hood` app with a `mark` of `helm-hi` to print "Opening airlock" in the dojo.
4655
4756We'll do this with an HTTP PUT request, and we'll include the cookie we obtained when we authenticated in the `Cookie` header. The URL path we'll make the request to will be `http://localhost:8080/~/channel/mychannel`. The last part of the path is the channel `UID` - the name for our new channel. Normally you'd use the current unix time plus a hash to ensure uniqueness, but in this case we'll just use `mychannel` for simplicity.
@@ -99,7 +108,7 @@ curl --header "Content-Type: application/json" \
99108 http://localhost:8080/~/channel/my-channel
100109```
101110
102−Notice we've incremented the `id` to `2`, as request IDs must be sequential.
111+Notice we've incremented the `id` to `2`. Eyre doesn't require IDs to be sequential, merely numerical and unique, but sequential IDs are typically the most practical.
103112
104113Back in the event stream, we'll see a positive watch ack as a [subscribe](@/docs/arvo/eyre/external-api-ref.md#watch-ack) `response`, meaning the subscription has been successful:
105114
@@ -108,14 +117,14 @@ id: 1
108117data: {"ok":"ok","id":2,"response":"subscribe"}
109118```
110119
111−Now we'll try trigger an event on our event stream. In fakezod's landscape, create a new chat channel named "test". You should see the `fact` containing the `add-graph` `graph-update` come through on our channel in a [diff](@/docs/arvo/eyre/external-api-ref.md#diff) `response`:
120+Now we'll try trigger an event on our event stream. In fakezod's landscape, create a new chat channel named "test". You should see the `add-graph` `graph-update` come through on our channel in a [diff](@/docs/arvo/eyre/external-api-ref.md#diff) `response`:
112121
113122```
114123id: 2
115124data: {"json":{"graph-update":{"add-graph":{"graph":{},"resource":{"name":"test-1183","ship":"zod"},"mark":"graph-validator-chat","overwrite":false}}},"id":2,"response":"diff"}
116125```
117126
118−All `fact`s we receive must be acked so Eyre knows we've successfully received it. To do this we'll send an [ack](@/docs/arvo/eyre/external-api-ref.md#ack) `action` which specifies the `event-id` of the event in question - `2` in this case:
127+All events we receive must be `ack`ed so Eyre knows we've successfully received them. To do this we'll send an [ack](@/docs/arvo/eyre/external-api-ref.md#ack) `action` which specifies the `event-id` of the event in question - `2` in this case:
119128
120129```
121130curl --header "Content-Type: application/json" \
@@ -125,7 +134,9 @@ curl --header "Content-Type: application/json" \
125134 http://localhost:8080/~/channel/my-channel
126135```
127136
128−This same pattern would be repeated for all subsequent `fact`s. When we're finished, we can unsubscribe from `graph-store` `/update`. We do this by sending Eyre a [unsubscribe](@/docs/arvo/eyre/external-api-ref.md#unsubscribe) `action`, and specify the request ID of the original `subscribe` `action` in the `subscription` field - `2` in our case:
137+This same pattern would be repeated for all subsequent events. Note that when you `ack` one event, you also implicitly `ack` all previous events, so in this case event `1` will also be `ack`ed.
138+
139+When we're finished, we can unsubscribe from `graph-store` `/update`. We do this by sending Eyre a [unsubscribe](@/docs/arvo/eyre/external-api-ref.md#unsubscribe) `action`, and specify the request ID of the original `subscribe` `action` in the `subscription` field - `2` in our case:
129140
130141```
131142curl --header "Content-Type: application/json" \
@@ -135,7 +146,7 @@ curl --header "Content-Type: application/json" \
135146 http://localhost:8080/~/channel/my-channel
136147```
137148
138−Unlike `poke` and `subscribe` actions, Eyre doesn't ack `unsubscribe`s, but we'll now have stopped receiving `fact`s from `graph-store`.
149+Unlike `poke` and `subscribe` actions, Eyre doesn't acknowledge `unsubscribe`s, but we'll now have stopped receiving updates from `graph-store`.
139150
140151Finally, let's close the channel itself. We can do this simply by sending Eyre a [delete](@/docs/arvo/eyre/external-api-ref.md#delete-channel) `action`:
141152
@@ -153,21 +164,7 @@ With our channel deleted, we can now close the connection on the client side.
153164
154165Here we'll look at performing scries through Eyre. You can refer to the [Scry](@/docs/arvo/eyre/external-api-ref.md#scry) section of the [External API Reference](@/docs/arvo/eyre/external-api-ref.md) document for relevant details.
155166
156−The first thing we must do is obtain a session cookie by authenticating with our web login code. We'll use the unix `curl` utility and provide the default code for a fakezod:
157−
158−```
159−curl -i localhost:8080/~/login -X POST -d "password=lidlut-tabwed-pillex-ridrup"
160−```
161−
162−Eyre will respond with HTTP status 204 and a `set-cookie` header containing the cookie, which we'll use in the `cookie` header of subsequent requests:
163−
164−```
165−HTTP/1.1 204 ok
166−Date: Fri, 04 Jun 2021 10:15:15 GMT
167−Connection: keep-alive
168−Server: urbit/vere-1.5
169−set-cookie: urbauth-~zod=0v1.1pseu.tq7hs.hps2t.ltaf1.tmqjm; Path=/; Max-Age=604800
170−```
167+First we must obtain a session cookie by [authenticating](#authenticating).
171168
172169Having obtained a cookie, we can now try a scry. We'll scry the `graph-store` Gall agent on the `/x/keys` scry path, which will return the list of channels it has. If you don't already have any chat channels on your fakezod, go ahead and create one via landscape so it'll have something to return.
173170
@@ -237,21 +234,7 @@ Here's an extremely simple thread that takes a `vase` of `(unit json)` and just
237234(pure:m !>(json))
238235```
239236
240−In order to run it through Eyre, we must first obtain a session cookie by [authenticating](@/docs/arvo/eyre/external-api-ref.md#authentication) with our web login code. To do so, we'll make an HTTP POST request using the unix `curl` utility:
241−
242−```
243−curl -i localhost:8080/~/login -X POST -d "password=lidlut-tabwed-pillex-ridrup"
244−```
245−
246−Eyre will respond with a 204 status and a `set-cookie` header containing the cookie:
247−
248−```
249−HTTP/1.1 204 ok
250−Date: Sun, 06 Jun 2021 04:50:09 GMT
251−Connection: keep-alive
252−Server: urbit/vere-1.5
253−set-cookie: urbauth-~zod=0v6.h6t4q.2tkui.oeaqu.nihh9.i0qv6; Path=/; Max-Age=604800
254−```
237+First we must obtain a session cookie by [authenticating](#authenticating).
255238
256239Now we can try and run our thread. Spider (the Gall agent that manages threads) is bound to the `/spider` URL path, and expects the rest of the path to be `/{inputMark}/{thread}/{outputMark}`. Our `{thread}` is called `eyre-thread`, and both its `{inputMark}` and `{outputMark}` are `json`, so our URL path will be `/spider/json/eyre-agent/json`. Our request will be an HTTP POST request and the body will be some `json`, in this case `[{"foo": "bar"}]`:
257240
@@ -283,7 +266,7 @@ In many cases you'll just want to interact with Gall agents through the JSON API
283266
284267You can refer to the [%connect](@/docs/arvo/eyre/tasks.md#connect) section of the [Internal API Reference](@/docs/arvo/eyre/tasks.md) document for relevant details.
285268
286−Here's a Gall agent that demonstrates this method. It binds the URL path `/foo`, serves `<h1>Hello, World!</h1>` for GET requests and a `405` error for all others. It also prints information to the dojo as various things happen.
269+Here's a Gall agent that demonstrates this method. It binds the URL path `/foo`, serves `<h1>Hello, World!</h1>` for GET requests and a `405` error for all others. It also prints debug information to the terminal as various things happen.
287270
288271`eyre-agent.hoon`
289272
@@ -320,7 +303,7 @@ Here's a Gall agent that demonstrates this method. It binds the URL path `/foo`,
320303 =/ data=octs
321304 (as-octs:mimes:html '<h1>405 Method Not Allowed</h1>')
322305 =/ content-length=@t
323− (crip (skip (scow %ud p.data) |=(a=@tD =(a '.'))))
306+ (crip ((d-co:co 1) p.data))
324307 =/ =response-header:http
325308 :- 405
326309 :~ ['Content-Length' content-length]
@@ -338,7 +321,7 @@ Here's a Gall agent that demonstrates this method. It binds the URL path `/foo`,
338321 =/ data=octs
339322 (as-octs:mimes:html '<h1>Hello, World!</h1>')
340323 =/ content-length=@t
341− (crip (skip (scow %ud p.data) |=(a=@tD =(a '.'))))
324+ (crip ((d-co:co 1) p.data))
342325 =/ =response-header:http
343326 :- 200
344327 :~ ['Content-Length' content-length]
@@ -453,7 +436,7 @@ transfer-encoding: chunked
453436=/ data=octs
454437 (as-octs:mimes:html '<h1>Hello, World!</h1>')
455438=/ content-length=@t
456− (crip (skip (scow %ud p.data) |=(a=@tD =(a '.'))))
439+ (crip ((d-co:co 1) p.data))
457440=/ =response-header:http
458441 :- 200
459442 :~ ['Content-Length' content-length]
@@ -520,7 +503,7 @@ Here's a very simple generator that will just echo back the body of the request
520503=/ data=octs
521504 (as-octs:mimes:html msg)
522505=/ content-length=@t
523− (rsh [3 2] (scot %ui p.data))
506+ (crip ((d-co:co 1) p.data))
524507=/ =response-header:http
525508 :- 200
526509 :~ ['Content-Length' content-length]