18f7fca · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

Merge pull request #1224 from tinnus-napbus/eyre-examples-to-guide

18f7fcatinnus-napbus5 years ago

content/docs/arvo/eyre/_index.md+1−1

compare with master

unifiedsplit

@@ -26,6 +26,6 @@ The scry endpoints of Eyre.

27Reference documentation of the various data types used by Eyre.

29−## [Examples](/docs/arvo/eyre/examples)

29+## [Guide](/docs/arvo/eyre/guide)

31Practical examples of the different ways of using Eyre.

content/docs/arvo/eyre/external-api-ref.md+4−4

@@ -4,7 +4,7 @@ weight = 2

4template = "doc.html"

5+++

7−This document contains reference information about Eyre's external APIs including [the channel system](#channels) and [scries](#scry). Each section will also have practical examples in the [Examples](/docs/arvo/eyre/examples) document.

7+This document contains reference information about Eyre's external APIs including [the channel system](#channels) and [scries](#scry). Each section will also have practical examples in the [Guide](/docs/arvo/eyre/guide) document.

9## Authentication

@@ -14,7 +14,7 @@ To use Eyre's channel system, run threads or perform scries you must first obtai

14| ----------- | -------------------------------------- | ---------- | ----------------------------------------------------------------------------------- |

17−See the [examples](/docs/arvo/eyre/examples#authenticating) for an example of how to do this using the curl.

17+See the [Guide](/docs/arvo/eyre/guide#authenticating) for an example of how to do this using the curl.

19Eyre's response will include a `set-cookie` header like:

@@ -51,7 +51,7 @@ All the events that Eyre sends you on a channel must be [ack](#ack)ed so that Ey

52When you're finished with a channel, you can send Eyre a [delete action](#delete-channel) to close it.

54−See the [Using the Channel System](/docs/arvo/eyre/examples#using-the-channel-system) section of the [Examples](/docs/arvo/eyre/examples) document for a practical example.

54+See the [Using the Channel System](/docs/arvo/eyre/guide#using-channels) section of the [Guide](/docs/arvo/eyre/guide) document for a practical example.

56### HTTP Requests

@@ -352,7 +352,7 @@ The `{mark}` is the type you want returned. It needn't just be `json` as with th

352

353If your session cookie is invalid or missing, Eyre will respond with a 403 Forbidden status. If the scry endpoint cannot be found, Eyre will respond with a 404 Missing status. If the `mark` conversions can't be done, Eyre will respond with a 500 Internal Server Error status. Otherwise, Eyre will respond with a 200 OK status with the requested data in the body of the HTTP response.

354

355−See the [Scrying](/docs/arvo/eyre/examples#scrying) section of the [Examples](/docs/arvo/eyre/examples) document for a practical example.

355+See the [Scrying](/docs/arvo/eyre/guide#scrying) section of the [Guide](/docs/arvo/eyre/guide) document for a practical example.

356

357## Spider

358

content/docs/arvo/eyre/eyre.md+5−5

@@ -18,7 +18,7 @@ Eyre's channel system is the primary way of interacting with Gall agents from ou

19The channel system is designed to be extremely simple with just a handful of `action` and `response` JSON objects to deal. Essentially it's a thin layer on top of the underlying Gall agent interface. You can poke agents, subscribe for updates, etc, just like you would from within Urbit.

21−Detailed documentation of the channel system's JSON API is provided in the [External API Reference](/docs/arvo/eyre/external-api-ref) document with corresponding examples in the [Examples](/docs/arvo/eyre/examples#using-the-channel-system) document.

21+Detailed documentation of the channel system's JSON API is provided in the [External API Reference](/docs/arvo/eyre/external-api-ref) document with corresponding examples in the [Guide](/docs/arvo/eyre/guide#using-the-channel-system) document.

23## Scrying

@@ -34,19 +34,19 @@ Spider (the Gall agent that manages threads) has an Eyre binding that allows you

35Generators, which are like Hoon scripts, can also be used through Eyre. Rather than having a predefined JSON API, they instead handle HTTP requests and return HTTP responses directly, and are therefore a more complex case that you're less likely to use.

37−Their usage is explained in the [%serve](/docs/arvo/eyre/tasks#serve) section of the [Internal API Reference](/docs/arvo/eyre/tasks) documentation and a practical example is provided in the [Generators](/docs/arvo/eyre/examples#generators) section of the [Examples](/docs/arvo/eyre/examples) document.

37+Their usage is explained in the [%serve](/docs/arvo/eyre/tasks#serve) section of the [Internal API Reference](/docs/arvo/eyre/tasks) documentation and a practical example is provided in the [Generators](/docs/arvo/eyre/guide#generators) section of the [Guide](/docs/arvo/eyre/guide) document.

39## Direct HTTP Handling With Gall Agents

41As well as the [Channel System](#the-channel-system) and [Scries](#scrying), it's also possible for Gall agents to deal directly with HTTP requests. This method is much more complicated than the channel system so you're unlikely to use it unless you want to build a custom HTTP-based API or something like that.

43−This method is explained in the [%connect](/docs/arvo/eyre/tasks#connect) section of the [Internal API Reference](/docs/arvo/eyre/tasks) document and a detailed example is provided in the [Direct HTTP Handling With Gall Agents](/docs/arvo/eyre/examples#direct-http-handling-with-gall-agents) section of the [Examples](/docs/arvo/eyre/examples) document.

43+This method is explained in the [%connect](/docs/arvo/eyre/tasks#connect) section of the [Internal API Reference](/docs/arvo/eyre/tasks) document and a detailed example is provided in the [Agents: Direct HTTP](/docs/arvo/eyre/guide#agents-direct-http) section of the [Guide](/docs/arvo/eyre/guide) document.

45## Cross-Origin Resource Sharing

47Eyre supports both simple [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) requests and OPTIONS preflight requests. It has a CORS registry with three categories - `approved`, `rejected` and `requests`. Eyre will respond positively for origins in its `approved` list and negatively for all others. Eyre will add origins in requests that it doesn't have in either its `approved` or `rejected` lists to its `requests` list. Eyre always allows all methods and headers over CORS.

49−There are three generators - `+cors-registry`, `|cors-approve`, and `|cors-reject` to view, approve, and deny origins respectively from the dojo. Eyre also has [tasks](/docs/arvo/eyre/tasks) to [approve](/docs/arvo/eyre/tasks#approve-origin) and [reject](/docs/arvo/eyre/tasks#reject-origin) origins programmatically, and a number of [scry endpoints](/docs/arvo/eyre/scry) to query them. Examples are also included in the [Managing CORS Origins](/docs/arvo/eyre/examples#managing-cors-origins) section of the Examples document.

49+There are three generators - `+cors-registry`, `|cors-approve`, and `|cors-reject` to view, approve, and deny origins respectively from the dojo. Eyre also has [tasks](/docs/arvo/eyre/tasks) to [approve](/docs/arvo/eyre/tasks#approve-origin) and [reject](/docs/arvo/eyre/tasks#reject-origin) origins programmatically, and a number of [scry endpoints](/docs/arvo/eyre/scry) to query them. Examples are also included in the [Managing CORS Origins](/docs/arvo/eyre/guide#managing-cors-origins) section of the Guide document.

51## Sections

@@ -58,4 +58,4 @@ There are three generators - `+cors-registry`, `|cors-approve`, and `|cors-rejec

59[Data Types](/docs/arvo/eyre/data-types) - Reference documentation of the various data types used by Eyre.

61−[Examples](/docs/arvo/eyre/examples) - Practical examples of the different ways of using Eyre.

61+[Guide](/docs/arvo/eyre/guide) - Practical examples of the different ways of using Eyre.

content/docs/arvo/eyre/examples.md → content/docs/arvo/eyre/guide.mdrenamed+24−18

@@ -1,16 +1,22 @@

1+++

2−title = "Examples"

2+title = "Guide"

3weight = 6

4template = "doc.html"

5+++

7−This documents contains practical examples of the various ways of interacting with Eyre.

7+This document walks through practical examples of the various ways of interacting with Eyre. The [Basic](#basic) sections goes over the common methods of interacting through Eyre from an HTTP client, and the [Advanced](#advanced) section explains how to handle HTTP directly with generators and Gall agents.

9General documentation of the `task`s and methods described here are available in the [External API Reference](/docs/arvo/eyre/external-api-ref) document and the [Internal API Reference](/docs/arvo/eyre/tasks) document.

11−## Authenticating

11+## Basic

13+Eyre's channel system is the typical way of interacting with Gall agents from an HTTP client. It provides a simple JSON API for actions like pokes, watches, etc, and an SSE event stream for subscription updates. Additionally, Eyre has a scry interface so you can retrieve data in a more ad-hoc manner. These examples use `curl` to be more language agnostic and to show the nitty-gritty details. In practice you'd probably use an "airlock" library (like [http-api](https://github.com/urbit/urbit/tree/master/pkg/npm/http-api) for Javascript) which abstracts things like ack'ing events, incrementing event IDs, manually composing the JSON for actions, etc.

14+

15+It's advisable to have a read through the [External API Reference](/docs/arvo/eyre/external-api-ref) before going through these examples.

16+

17+### Authenticating

18+

13−In most cases we must obtain a valid session cookie by [authenticating](/docs/arvo/eyre/external-api-ref#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).

19+You must have a valid session cookie in order to use Eyre's interfaces (such as the channel system or scry interface). If your HTTP client is served from your ship, your browser will automatically add the session cookie it obtained upon login, so there's no need to worry about authentication in practice. If your client does not run in the browser or is not served by your ship, [authenticating](/docs/arvo/eyre/external-api-ref#authentication) with your web login code (which can be obtained by running `+code` in the dojo) is necessary.

15Here we'll try authenticating with the default fakezod code.

21Here we'll try authenticating with the default fakezod code.

@@ -32,7 +38,7 @@ set-cookie: urbauth-~zod=0v3.j2062.1prp1.qne4e.goq3h.ksudm; Path=/; Max-Age=6048

33The `urbauth-....` cookie can be now be included in subsequent requests (e.g. to the channel system) by providing it in a Cookie HTTP header.

39The `urbauth-....` cookie can be now be included in subsequent requests (e.g. to the channel system) by providing it in a Cookie HTTP header.

35−## Using The Channel System

41+### Using Channels

37Here we'll look at a practical example of Eyre's channel system. You can refer to the [Channels](/docs/arvo/eyre/external-api-ref#channels) section of the [External API Reference](/docs/arvo/eyre/external-api-ref) document for relevant details.

43Here we'll look at a practical example of Eyre's channel system. You can refer to the [Channels](/docs/arvo/eyre/external-api-ref#channels) section of the [External API Reference](/docs/arvo/eyre/external-api-ref) document for relevant details.

@@ -147,7 +153,7 @@ curl --header "Content-Type: application/json" \

147

153

148With our channel deleted, we can now close the connection on the client side.

154With our channel deleted, we can now close the connection on the client side.

149

155

150−## Scrying

156+### Scrying

151

157

152Here we'll look at performing scries through Eyre. You can refer to the [Scry](/docs/arvo/eyre/external-api-ref#scry) section of the [External API Reference](/docs/arvo/eyre/external-api-ref) document for relevant details.

158Here we'll look at performing scries through Eyre. You can refer to the [Scry](/docs/arvo/eyre/external-api-ref#scry) section of the [External API Reference](/docs/arvo/eyre/external-api-ref) document for relevant details.

153

159

@@ -201,9 +207,13 @@ content-type: text/html

201<html><head><title>404 Not Found</title></head><body><h1>Not Found</h1><p>There was an error while handling the request for /foo/bar/baz.json.</p><code>no scry result</code></body></html>

207<html><head><title>404 Not Found</title></head><body><h1>Not Found</h1><p>There was an error while handling the request for /foo/bar/baz.json.</p><code>no scry result</code></body></html>

202```

208```

203

209

204−## Direct HTTP Handling With Gall Agents

210+## Advanced

205

211

206−In many cases you'll just want to interact with Gall agents through the JSON API of the channel system, but it's also possible to bypass all that and just deal with HTTP requests directly. Here we'll take a look at how that practically works.

212+Rather than using things like Eyre's channel system described in the [Basic](#basic) section, it's possible to handle HTTP requests directly in Gall agents or generators. This is useful if you want to implement a custom API or work with `sail` to dynamically compose HTML inside an agent.

213+

214+### Agents: Direct HTTP

215+

216+Here we'll look at handling HTTP requests directly in Gall agents rather than using Eyre's channel system.

207

217

208You can refer to the [%connect](/docs/arvo/eyre/tasks#connect) section of the [Internal API Reference](/docs/arvo/eyre/tasks) document for relevant details.

218You can refer to the [%connect](/docs/arvo/eyre/tasks#connect) section of the [Internal API Reference](/docs/arvo/eyre/tasks) document for relevant details.

209

219

@@ -309,19 +319,15 @@ Note that this example does a lot of things manually for demonstrative purposes.

309Save the above to `/app/eyre-agent.hoon`. Commit it:

319Save the above to `/app/eyre-agent.hoon`. Commit it:

310

320

311```

321```

312−> |commit %home

322+> |commit %base

313>=

323>=

314−+ /~zod/home/2/app/eyre-agent/hoon

324++ /~zod/base/2/app/eyre-agent/hoon

315```

325```

316

326

317...and start it:

327...and start it:

318

328

319```

329```

320−> |start %eyre-agent

321−>=

322−gall: loading %eyre-agent

323−activated app home/eyre-agent

324−[unlinked from [p=~zod q=%eyre-agent]]

330+> |rein %base [& %eyre-agent]

325```

331```

326

332

327Now, first we need to bind a URL to our app. In the `++ on-poke` arm, our agent will send a [%connect](/docs/arvo/eyre/tasks#connect) `task` to Eyre when poked with `%bind`:

333Now, first we need to bind a URL to our app. In the `++ on-poke` arm, our agent will send a [%connect](/docs/arvo/eyre/tasks#connect) `task` to Eyre when poked with `%bind`:

@@ -424,13 +430,13 @@ Eyre subscribed to /http-response/~.eyre_0v3.1knjk.l544e.5uds6.fn9l2.f8929.

424

430

425This is a very rudimentary app but it demonstrates the basic mechanics of dealing with HTTP requests and serving responses.

431This is a very rudimentary app but it demonstrates the basic mechanics of dealing with HTTP requests and serving responses.

426

432

427−## Generators

433+### Generators

428

434

429Here we'll look at running a generator via Eyre. Eyre doesn't have a mediated JSON API for generators, instead it just passes through the HTTP request and returns the HTTP response composed by the generator.

435Here we'll look at running a generator via Eyre. Eyre doesn't have a mediated JSON API for generators, instead it just passes through the HTTP request and returns the HTTP response composed by the generator.

430

436

431You can refer to the [%serve](/docs/arvo/eyre/tasks#serve) section of the [Internal API Reference](/docs/arvo/eyre/tasks) document for relevant details.

437You can refer to the [%serve](/docs/arvo/eyre/tasks#serve) section of the [Internal API Reference](/docs/arvo/eyre/tasks) document for relevant details.

432

438

433−Here's a very simple generator that will just echo back the body of the request (if available) along with the current datetime. You can save it in the `/gen` directory and `|commit %home`.

439+Here's a very simple generator that will just echo back the body of the request (if available) along with the current datetime. You can save it in the `/gen` directory and `|commit %base`.

434

440

435Note that this example does some things manually for demonstrative purposes. In practice you'd likely want to use a library like `/lib/server.hoon` to cut down on boilerplate code.

441Note that this example does some things manually for demonstrative purposes. In practice you'd likely want to use a library like `/lib/server.hoon` to cut down on boilerplate code.

436

442

@@ -478,7 +484,7 @@ The [$binding](/docs/arvo/eyre/data-types#binding) specifies the site and URL pa

478Let's bind our generator to the `/mygen` URL path with the `|pass` command in the dojo:

484Let's bind our generator to the `/mygen` URL path with the `|pass` command in the dojo:

479

485

480```

486```

481−|pass [%e [%serve `/mygen %home /gen/eyre-gen/hoon ~]]

487+|pass [%e [%serve `/mygen %base /gen/eyre-gen/hoon ~]]

482```

488```

483

489

484Note that Eyre responds with a `%bound` `gift` to indicate whether the binding succeeded but `|pass` doesn't take such responses so it's not shown.

490Note that Eyre responds with a `%bound` `gift` to indicate whether the binding succeeded but `|pass` doesn't take such responses so it's not shown.

content/docs/arvo/eyre/tasks.md+5−5

@@ -6,7 +6,7 @@ template = "doc.html"

7This document details all the `task`s you're likely to use to interact with Eyre, as well as the `gift`s you'll receive in response.

9−The primary way of interacting with Eyre is from the outside with HTTP requests. As a result, most of its `task`s are only used internally and you're unlikely to need to deal with them directly. The ones you may want to use in certain cases are [%connect](#connect), [%serve](#serve), [%disconnect](#disconnect), [%approve-origin](#approve-origin) and [%reject-origin](#reject-origin), and they are also demonstrated in the [Examples](/docs/arvo/eyre/examples) document. The rest are just documented for completeness.

9+The primary way of interacting with Eyre is from the outside with HTTP requests. As a result, most of its `task`s are only used internally and you're unlikely to need to deal with them directly. The ones you may want to use in certain cases are [%connect](#connect), [%serve](#serve), [%disconnect](#disconnect), [%approve-origin](#approve-origin) and [%reject-origin](#reject-origin), and they are also demonstrated in the [Guide](/docs/arvo/eyre/guide) document. The rest are just documented for completeness.

11Many of the types referenced are detailed in the [Data Types](/docs/arvo/eyre/data-types) document. It may also be useful to look at the `+eyre` section of `/sys/lull.hoon` in Arvo where these `task`s, `gift`s and data structures are defined.

@@ -110,7 +110,7 @@ The `accepted` field says whether the binding succeeded and the `binding` is the

110

111#### Example

112

113−See the [Direct HTTP Handling With Gall Agents](/docs/arvo/eyre/examples#direct-http-handling-with-gall-agents) section of the [Examples](/docs/arvo/eyre/examples) document for an example.

113+See the [Agents: Direct HTTP](/docs/arvo/eyre/guide#agents-direct-http) section of the [Guide](/docs/arvo/eyre/guide) document for an example.

114

115## `%serve`

116

@@ -146,7 +146,7 @@ Eyre will return a `%bound` `gift` as described at the end of the [%connect](#co

146

147#### Example

148

149−See the [Generators](/docs/arvo/eyre/examples#generators) section of the [Examples](/docs/arvo/eyre/examples) document for an example.

149+See the [Generators](/docs/arvo/eyre/guide#generators) section of the [Guide](/docs/arvo/eyre/guide) document for an example.

150

151## `%disconnect`

152

@@ -192,7 +192,7 @@ Eyre returns no `gift` in response to a `%approve-origin` `task`.

192

193#### Example

194

195−See the [Managing CORS Origins](/docs/arvo/eyre/examples#managing-cors-origins) section of the [Examples](/docs/arvo/eyre/examples) document for an example.

195+See the [Managing CORS Origins](/docs/arvo/eyre/guide#managing-cors-origins) section of the [Guide](/docs/arvo/eyre/guide) document for an example.

196

197## `%reject-origin`

198

@@ -210,4 +210,4 @@ Eyre returns no `gift` in response to a `%reject-origin` `task`.

210

211#### Example

212

213−See the [Managing CORS Origins](/docs/arvo/eyre/examples#managing-cors-origins) section of the [Examples](/docs/arvo/eyre/examples) document for an example.

213+See the [Managing CORS Origins](/docs/arvo/eyre/guide#managing-cors-origins) section of the [Guide](/docs/arvo/eyre/guide) document for an example.

content/docs/userspace/threads/http-api.md+1−1

@@ -46,7 +46,7 @@ Here's an extremely simple thread that takes a `vase` of `(unit json)` and just

46(pure:m !>(json))

47```

49−First we must obtain a session cookie by [authenticating](/docs/arvo/eyre/examples#authenticating).

49+First we must obtain a session cookie by [authenticating](/docs/arvo/eyre/guide#authenticating).

51Now we can try and run our thread. Spider is bound to the `/spider` URL path, and expects the rest of the path to be `/{desk}/{inputMark}/{thread}/{outputMark}`. Our `{thread}` is called `eyre-thread` and is in the `%base` `{desk}`. Both its `{inputMark}` and `{outputMark}` are `json`. Therefore, our URL path will be `/spider/base/json/eyre-agent/json`. Our request will be an HTTP POST request and the body will be some `json`, in this case `[{"foo": "bar"}]`: