80f32da · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

move spider eyre docs to userspace/threads

80f32datinnus-napbus5 years ago

arvo/eyre/examples.md−47

compare with master

unifiedsplit

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

10- [Authenticating](#authenticating)

11- [Using the Channel System](#using-the-channel-system)

12- [Scrying](#scrying)

13−- [Running Threads With Spider](#running-threads-with-spider)

14- [Direct HTTP Handling With Gall Agents](#direct-http-handling-with-gall-agents)

13- [Direct HTTP Handling With Gall Agents](#direct-http-handling-with-gall-agents)

15- [Generators](#generators)

14- [Generators](#generators)

16- [Managing CORS Origins](#managing-cors-origins)

15- [Managing CORS Origins](#managing-cors-origins)

@@ -214,52 +213,6 @@ content-type: text/html

214<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>

213<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>

215```

214```

216

215

217−# Running Threads With Spider

218−

219−Here we'll look at running Spider threads through Eyre. You can refer to the [Spider](@/docs/arvo/eyre/external-api-ref.md#spider) section of the [External API Reference](@/docs/arvo/eyre/external-api-ref.md) document for relevant details.

220−

221−Here's an extremely simple thread that takes a `vase` of `(unit json)` and just returns the `json` in a new `vase`. You can save it in `/ted` and `|commit %home`:

222−

223−`eyre-thread.hoon`

224−

225−```hoon

226−/- spider

227−=, strand=strand:spider

228−^- thread:spider

229−|= arg=vase

230−=/ m (strand ,vase)

231−^- form:m

232−=/ =json

233− (need !<((unit json) arg))

234−(pure:m !>(json))

235−```

236−

237−First we must obtain a session cookie by [authenticating](#authenticating).

238−

239−Now 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"}]`:

240−

241−```

242−curl -i --header "Content-Type: application/json" \

243− --cookie "urbauth-~zod=0v6.h6t4q.2tkui.oeaqu.nihh9.i0qv6" \

244− --request POST \

245− --data '[{"foo": "bar"}]' \

246− http://localhost:8080/spider/json/eyre-thread/json

247−```

248−

249−Spider will run the thread and the result will be returned through Eyre in the body of an HTTP response with a 200 status code:

250−

251−```

252−HTTP/1.1 200 ok

253−Date: Sun, 06 Jun 2021 05:32:45 GMT

254−Connection: keep-alive

255−Server: urbit/vere-1.5

256−set-cookie: urbauth-~zod=0v6.h6t4q.2tkui.oeaqu.nihh9.i0qv6; Path=/; Max-Age=604800

257−content-type: application/json

258−transfer-encoding: chunked

259−

260−[{"foo":"bar"}]

261−```

262−

263# Direct HTTP Handling With Gall Agents

216# Direct HTTP Handling With Gall Agents

264

217

265In 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.

218In 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.

arvo/eyre/external-api-ref.md+2−24

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

27# Introduction

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

29+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.md) document.

31# Authentication

@@ -376,26 +376,4 @@ See the [Scrying](@/docs/arvo/eyre/examples.md#scrying) section of the [Examples

376

377# Spider

378

379−Spider (the Gall agent that manages threads) has an Eyre binding which allows threads to be run via [authenticated](#authentication) HTTP POST requests.

379+See the [HTTP API](@/docs/userspace/threads/http-api.md) section of the [Threads](@/docs/userspace/threads/overview.md) documentation.

380−

381−Spider is bound to the `/spider` URL path, and expects the requested URL to look like:

382−

383−```

384−http{s}://{host}/spider/{inputMark}/{threadName}/{outputMark}

385−```

386−

387−The `inputMark` is the `mark` the thread takes. The `threadName` is the name of the thread, e.g. `foo` for `/ted/foo/hoon`. The `outputMark` is the `mark` the thread produces. You may also include a file extension though it doesn't have an effect.

388−

389−When Spider receives an HTTP request, the following steps happen:

390−

391−1. It converts the raw body of the message to `json` using `de-json:html`

392−2. It creates a `tube:clay` (`mark` conversion gate) from `json` to whatever input `mark` you've specified and does the conversion.

393−3. It runs the specified thread and provides a `vase` of `(unit inputMark)` as the argument.

394−4. The thread does its thing and finally produces its result as a `vase` of `outputMark`.

395−5. Spider creates another `tube:clay` from the output `mark` to `json` and converts it.

396−6. It converts the `json` back into raw data suitable for the HTTP response body using `en-json:html`.

397−7. Finally, it composes the HTTP response and passes it back to Eyre which passes it on to the client.

398−

399−Thus, it's important to understand that the original HTTP request and final HTTP response must contain JSON data, and therefore the input & output `mark`s you specify must each have a `mark` file in `/mar` that includes a conversion method for `json -> inputMark` and `outputMark -> json` respectively.

400−

401−See the [Running Threads With Spider](@/docs/arvo/eyre/examples.md#running-threads-with-spider) section of the [Examples](@/docs/arvo/eyre/examples.md) document for a practical example.

arvo/eyre/eyre.md+1−3

@@ -28,9 +28,7 @@ Details of Eyre's scry API are in the [Scry](@/docs/arvo/eyre/external-api-ref.m

29# Spider Threads

31−Threads are like transient Gall agents which typically handle complex IO operations for Gall agents (you can read more about them [here](@/docs/userspace/threads/overview.md)). Spider (the Gall agent that manages threads) has an Eyre binding that allows you to run threads through Eyre.

31+Spider (the Gall agent that manages threads) has an Eyre binding that allows you to run threads through Eyre. Spider's [HTTP API](@/docs/userspace/threads/http-api.md) is not part of Eyre proper, so is documented separately in the [Threads](@/docs/userspace/threads/overview.md) documentation.

32−

33−The [Spider](@/docs/arvo/eyre/external-api-ref.md#spider) section of the [External API Reference](@/docs/arvo/eyre/external-api-ref.md) document explains their usage, and the [Running Threads With Spider](@/docs/arvo/eyre/examples.md#running-threads-with-spider) section of the [Examples](@/docs/arvo/eyre/examples.md) document provides a practical example.

35# Generators

33# Generators

userspace/threads/_index.md+4

@@ -22,6 +22,10 @@ Tutorial and explanation of interacting with threads from agents.

23A collection of example threads and how-tos.

25+## [HTTP API](@/docs/userspace/threads/http-api.md)

26+

27+An overview and practical example of running threads externally via HTTP requests.

28+

25## [Reference](@/docs/userspace/threads/reference.md)

29## [Reference](@/docs/userspace/threads/reference.md)

27Basic reference for interacting with threads via the Gall agent Spider.

31Basic reference for interacting with threads via the Gall agent Spider.

userspace/threads/http-api.mdnew file+74

@@ -0,0 +1,74 @@

1++++

2+title = "HTTP API"

3+weight = 2

4+template = "doc.html"

5++++

7+Spider has an Eyre binding which allows threads to be run externally via [authenticated](@/docs/arvo/eyre/external-api-ref.md#authentication) HTTP POST requests.

9+Spider is bound to the `/spider` URL path, and expects the requested URL to look like:

10+

11+```

12+http{s}://{host}/spider/{inputMark}/{threadName}/{outputMark}

13+```

14+

15+The `inputMark` is the `mark` the thread takes. The `threadName` is the name of the thread, e.g. `foo` for `/ted/foo/hoon`. The `outputMark` is the `mark` the thread produces. You may also include a file extension though it doesn't have an effect.

16+

17+When Spider receives an HTTP request, the following steps happen:

18+

19+1. It converts the raw body of the message to `json` using `de-json:html`

20+2. It creates a `tube:clay` (`mark` conversion gate) from `json` to whatever input `mark` you've specified and does the conversion.

21+3. It runs the specified thread and provides a `vase` of `(unit inputMark)` as the argument.

22+4. The thread does its thing and finally produces its result as a `vase` of `outputMark`.

23+5. Spider creates another `tube:clay` from the output `mark` to `json` and converts it.

24+6. It converts the `json` back into raw data suitable for the HTTP response body using `en-json:html`.

25+7. Finally, it composes the HTTP response and passes it back to Eyre which passes it on to the client.

26+

27+Thus, it's important to understand that the original HTTP request and final HTTP response must contain JSON data, and therefore the input & output `mark`s you specify must each have a `mark` file in `/mar` that includes a conversion method for `json -> inputMark` and `outputMark -> json` respectively.

28+

29+

30+# Example

31+

32+Here we'll look at running Spider threads through Eyre.

33+

34+Here's an extremely simple thread that takes a `vase` of `(unit json)` and just returns the `json` in a new `vase`. You can save it in `/ted` and `|commit %home`:

35+

36+`eyre-thread.hoon`

37+

38+```hoon

39+/- spider

40+=, strand=strand:spider

41+^- thread:spider

42+|= arg=vase

43+=/ m (strand ,vase)

44+^- form:m

45+=/ =json

46+ (need !<((unit json) arg))

47+(pure:m !>(json))

48+```

49+

50+First we must obtain a session cookie by [authenticating](@/docs/arvo/eyre/examples.md#authenticating).

51+

52+Now we can try and run our thread. Spider 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"}]`:

53+

54+```

55+curl -i --header "Content-Type: application/json" \

56+ --cookie "urbauth-~zod=0v6.h6t4q.2tkui.oeaqu.nihh9.i0qv6" \

57+ --request POST \

58+ --data '[{"foo": "bar"}]' \

59+ http://localhost:8080/spider/json/eyre-thread/json

60+```

61+

62+Spider will run the thread and the result will be returned through Eyre in the body of an HTTP response with a 200 status code:

63+

64+```

65+HTTP/1.1 200 ok

66+Date: Sun, 06 Jun 2021 05:32:45 GMT

67+Connection: keep-alive

68+Server: urbit/vere-1.5

69+set-cookie: urbauth-~zod=0v6.h6t4q.2tkui.oeaqu.nihh9.i0qv6; Path=/; Max-Age=604800

70+content-type: application/json

71+transfer-encoding: chunked

72+

73+[{"foo":"bar"}]

74+```

userspace/threads/overview.md+3

@@ -77,5 +77,8 @@ These docs walk through the basics of interacting with threads from gall agents.

77- [Scry](@/docs/userspace/threads/examples/scry.md) - Scry arvo or an agent.

78- [Take a fact](@/docs/userspace/threads/examples/take-fact.md) - Subscribe to an agent and receive a fact.

80+## [HTTP API](@/docs/userspace/threads/http-api.md)

81+An overview and practical example of running threads externally with HTTP requests.

82+

80## [Reference](@/docs/userspace/threads/reference.md)

83## [Reference](@/docs/userspace/threads/reference.md)

81Basic reference information. For usage of particular `strandio` functions just refer directly to `/lib/strandio/hoon` since they're largely self-explanatory.

84Basic reference information. For usage of particular `strandio` functions just refer directly to `/lib/strandio/hoon` since they're largely self-explanatory.