785c85a · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

Fix eyre docs (#734)

785c85atinnus-napbus5 years ago

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

compare with master

unifiedsplit

@@ -14,18 +14,18 @@ An overview of Eyre and its capabilities.

15Details of Eyre's external API including the channel system's JSON API.

17−## [Internal API Reference](@/docs/arvo/eyre/tasks.md)

17+## [Internal API Reference](/docs/arvo/eyre/tasks)

19The `task`s Eyre takes and the `gift`s it returns.

21−## [Scry Reference](@/docs/arvo/eyre/scry.md)

21+## [Scry Reference](/docs/arvo/eyre/scry)

23The scry endpoints of Eyre.

25−## [Data Types](@/docs/arvo/eyre/data-types.md)

25+## [Data Types](/docs/arvo/eyre/data-types)

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

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

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

31Practical examples of the different ways of using Eyre.

content/docs/arvo/eyre/data-types.md+32−33

@@ -4,16 +4,15 @@ weight = 5

4template = "doc.html"

5+++

7−# Introduction

8−

9This document describes the data types used by Eyre as defined in `/sys/lull.hoon`. It's separated into two sections:

7This document describes the data types used by Eyre as defined in `/sys/lull.hoon`. It's separated into two sections:

11−- [Eyre](#eyre) - Eyre-specific data types.

9+[Eyre](#eyre) - Eyre-specific data types.

10+

12−- [HTTP](#http) - HTTP data types shared between Eyre and Iris.

11+[HTTP](#http) - HTTP data types shared between Eyre and Iris.

14−# Eyre

13+## Eyre

16−## `$origin`

15+### `$origin`

18```hoon

17```hoon

19+$ origin @torigin

18+$ origin @torigin

@@ -21,7 +20,7 @@ This document describes the data types used by Eyre as defined in `/sys/lull.hoo

22A single CORS origin as used in an HTTP Origin header and the [$cors-registry](#cors-registry).

21A single CORS origin as used in an HTTP Origin header and the [$cors-registry](#cors-registry).

24−## `$cors-registry`

23+### `$cors-registry`

26```hoon

25```hoon

27+$ cors-registry

26+$ cors-registry

@@ -33,7 +32,7 @@ A single CORS origin as used in an HTTP Origin header and the [$cors-registry](#

34CORS origins categorised by approval status. The `requests` `set` contains all [$origin](#origin)s Eyre has received in the headers of HTTP requests that have not been explicitly approved or rejected. The `approved` and `rejected` `set`s are those that have been explicitly approved or rejected.

33CORS origins categorised by approval status. The `requests` `set` contains all [$origin](#origin)s Eyre has received in the headers of HTTP requests that have not been explicitly approved or rejected. The `approved` and `rejected` `set`s are those that have been explicitly approved or rejected.

36−## `$outstanding-connection`

35+### `$outstanding-connection`

38```hoon

37```hoon

39+$ outstanding-connection

38+$ outstanding-connection

@@ -46,15 +45,15 @@ CORS origins categorised by approval status. The `requests` `set` contains all [

47An HTTP connection that is currently open. The [$action](#action) is how it's being handled (e.g. by a Gall app, the channel system, etc). The [$inbound-request](#inbound-request) is the original request which opened the connection. The `response-header` contains the status code and headers. The `bytes-sent` is the total bytes sent so far in response.

46An HTTP connection that is currently open. The [$action](#action) is how it's being handled (e.g. by a Gall app, the channel system, etc). The [$inbound-request](#inbound-request) is the original request which opened the connection. The `response-header` contains the status code and headers. The `bytes-sent` is the total bytes sent so far in response.

49−## `$authentication-state`

48+### `$authentication-state`

51```hoon

50```hoon

52+$ authentication-state sessions=(map @uv session)

51+$ authentication-state sessions=(map @uv session)

53```

52```

55−This represents the authentication state of all sessions. It maps session cookies (without the `urbauth-<ship>=` prefix) to [$session](#session)s.

54+This represents the authentication state of all sessions. It maps session cookies (without the `urbauth-{SHIP}=` prefix) to [$session](#session)s.

57−## `$session`

56+### `$session`

59```hoon

58```hoon

60+$ session

59+$ session

@@ -65,7 +64,7 @@ This represents the authentication state of all sessions. It maps session cookie

66This represents server-side data about a session. The `expiry-time` is when the `session` expires and `channels` is the `set` of [$channel](#channel) names opened by the session.

65This represents server-side data about a session. The `expiry-time` is when the `session` expires and `channels` is the `set` of [$channel](#channel) names opened by the session.

68−## `$channel-state`

67+### `$channel-state`

70```hoon

69```hoon

71+$ channel-state

70+$ channel-state

@@ -76,7 +75,7 @@ This represents server-side data about a session. The `expiry-time` is when the

77The state used by the channel system. The `session` is a `map` between channel names and [$channel](#channel)s and the `duct-to-key` `map`s `duct`s to `channel` names.

76The state used by the channel system. The `session` is a `map` between channel names and [$channel](#channel)s and the `duct-to-key` `map`s `duct`s to `channel` names.

79−## `$timer`

78+### `$timer`

81```hoon

80```hoon

82+$ timer

81+$ timer

@@ -87,7 +86,7 @@ The state used by the channel system. The `session` is a `map` between channel n

88A reference to a timer so it can be cancelled or updated. The `date` is when it will fire and the `duct` is what set the timer.

87A reference to a timer so it can be cancelled or updated. The `date` is when it will fire and the `duct` is what set the timer.

90−## `$channel-event`

89+### `$channel-event`

92```hoon

91```hoon

93+$ channel-event

92+$ channel-event

@@ -100,7 +99,7 @@ A reference to a timer so it can be cancelled or updated. The `date` is when it

100

101An unacknowledged event in the channel system.

100An unacknowledged event in the channel system.

102

101

103−## `$channel`

102+### `$channel`

104

103

105```hoon

104```hoon

106+$ channel

105+$ channel

@@ -116,7 +115,7 @@ An unacknowledged event in the channel system.

116

115

117This is the state of a particular channel in the channel system. The `state` is either the expiration time or the duct currently listening. The `next-id` is the next event ID to be used in the event stream. The `last-ack` is the date of the last client ack and is used for clog calculations in combination with `unacked`. The `events` queue contains all unacked events - `id` is the server-set event ID, `request-id` is the client-set request ID and the [$channel-event](#channel-event) is the event itself. The `unacked` `map` contains the unacked event count per `request-id` and is used for clog calculations. The `subscriptions` `map` contains gall subscriptions by `request-id`. The `heartbeat` is the SSE heartbeat [$timer](#timer).

116This is the state of a particular channel in the channel system. The `state` is either the expiration time or the duct currently listening. The `next-id` is the next event ID to be used in the event stream. The `last-ack` is the date of the last client ack and is used for clog calculations in combination with `unacked`. The `events` queue contains all unacked events - `id` is the server-set event ID, `request-id` is the client-set request ID and the [$channel-event](#channel-event) is the event itself. The `unacked` `map` contains the unacked event count per `request-id` and is used for clog calculations. The `subscriptions` `map` contains gall subscriptions by `request-id`. The `heartbeat` is the SSE heartbeat [$timer](#timer).

118

117

119−## `$binding`

118+### `$binding`

120

119

121```hoon

120```hoon

122+$ binding

121+$ binding

@@ -127,7 +126,7 @@ This is the state of a particular channel in the channel system. The `state` is

127

126

128A `binding` is a rule to match a URL `path` and optional `site` domain which can then be tied to an [$action](#action). A `path` of `/foo` will also match `/foo/bar`, `/foo/bar/baz`, etc. If the `site` is `~` it will be determined implicitly. A binding must be unique.

127A `binding` is a rule to match a URL `path` and optional `site` domain which can then be tied to an [$action](#action). A `path` of `/foo` will also match `/foo/bar`, `/foo/bar/baz`, etc. If the `site` is `~` it will be determined implicitly. A binding must be unique.

129

128

130−## `$action`

129+### `$action`

131

130

132```hoon

131```hoon

133+$ action

132+$ action

@@ -143,7 +142,7 @@ A `binding` is a rule to match a URL `path` and optional `site` domain which can

143

142

144The action to take when a [$binding](#binding) matches an incoming HTTP request.

143The action to take when a [$binding](#binding) matches an incoming HTTP request.

145

144

146−## `$generator`

145+### `$generator`

147

146

148```hoon

147```hoon

149+$ generator

148+$ generator

@@ -155,7 +154,7 @@ The action to take when a [$binding](#binding) matches an incoming HTTP request.

155

154

156This refers to a generator on a local ship that can handle requests. Note that serving generators via Eyre is not fully implmented and should not be used.

155This refers to a generator on a local ship that can handle requests. Note that serving generators via Eyre is not fully implmented and should not be used.

157

156

158−## `$http-config`

157+### `$http-config`

159

158

160```hoon

159```hoon

161+$ http-config

160+$ http-config

@@ -168,7 +167,7 @@ This refers to a generator on a local ship that can handle requests. Note that s

168

167

169The configuration of the runtime HTTP server itself. The `secure` field contains the PEM-encoded RSA private key and certificate or certificate chain when using HTTPS, and otherwise is `~` when using plain HTTP. The `proxy` field is not currently used. The `log` field turns on HTTP(S) access logs but is not currently implemented. The `redirect` field turns on 301 redirects to upgrade HTTP to HTTPS if the `key` and `cert` are set in `secure`.

168The configuration of the runtime HTTP server itself. The `secure` field contains the PEM-encoded RSA private key and certificate or certificate chain when using HTTPS, and otherwise is `~` when using plain HTTP. The `proxy` field is not currently used. The `log` field turns on HTTP(S) access logs but is not currently implemented. The `redirect` field turns on 301 redirects to upgrade HTTP to HTTPS if the `key` and `cert` are set in `secure`.

170

169

171−## `$http-rule`

170+### `$http-rule`

172

171

173```hoon

172```hoon

174+$ http-rule

173+$ http-rule

@@ -179,7 +178,7 @@ The configuration of the runtime HTTP server itself. The `secure` field contains

179

178

180This is for updating the server configuration. In the case of `%cert`, a `cert` of `~` clears the HTTPS cert & key, otherwise `cert` contains the PEM-encoded RSA private key and certificate or certificate chain. In the case of `%turf`, a `%put` `action` sets a domain name and a `%del` `action` removes it. The [$turf](#turf) contains the domain name.

179This is for updating the server configuration. In the case of `%cert`, a `cert` of `~` clears the HTTPS cert & key, otherwise `cert` contains the PEM-encoded RSA private key and certificate or certificate chain. In the case of `%turf`, a `%put` `action` sets a domain name and a `%del` `action` removes it. The [$turf](#turf) contains the domain name.

181

180

182−## `$address`

181+### `$address`

183

182

184```hoon

183```hoon

185+$ address

184+$ address

@@ -190,7 +189,7 @@ This is for updating the server configuration. In the case of `%cert`, a `cert`

190

189

191A client IP address.

190A client IP address.

192

191

193−## `$inbound-request`

192+### `$inbound-request`

194

193

195```hoon

194```hoon

196+$ inbound-request

195+$ inbound-request

@@ -201,11 +200,11 @@ A client IP address.

201 ==

200 ==

202```

201```

203

202

204−An inbound HTTP request and metadata. The `authenticated` field says whether the request was made with a valid session cookie. The `secure` field says whether it was made with HTTPS. The [$address](#address) is the IP address from which the request originated, except if it came from localhost and included a `Forwarded` header, in which case it's the address specified in that header. The [$request:http](#request-http) contains the HTTP request itself.

203+An inbound HTTP request and metadata. The `authenticated` field says whether the request was made with a valid session cookie. The `secure` field says whether it was made with HTTPS. The [$address](#address) is the IP address from which the request originated, except if it came from localhost and included a `Forwarded` header, in which case it's the address specified in that header. The [$request:http](#requesthttp) contains the HTTP request itself.

205

204

206−# HTTP

205+## HTTP

207

206

208−## `$header-list:http`

207+### `$header-list:http`

209

208

210```hoon

209```hoon

211+$ header-list (list [key=@t value=@t])

210+$ header-list (list [key=@t value=@t])

@@ -213,7 +212,7 @@ An inbound HTTP request and metadata. The `authenticated` field says whether the

213

212

214An ordered list of HTTP headers. The `key` is the header name e.g `'Content-Type'` and the `value` is the value e.g. `text/html`.

213An ordered list of HTTP headers. The `key` is the header name e.g `'Content-Type'` and the `value` is the value e.g. `text/html`.

215

214

216−## `$method:http`

215+### `$method:http`

217

216

218```hoon

217```hoon

219+$ method

218+$ method

@@ -230,7 +229,7 @@ An ordered list of HTTP headers. The `key` is the header name e.g `'Content-Type

230

229

231An HTTP method.

230An HTTP method.

232

231

233−## `$request:http`

232+### `$request:http`

234

233

235```hoon

234```hoon

236+$ request

235+$ request

@@ -241,9 +240,9 @@ An HTTP method.

241 ==

240 ==

242```

241```

243

242

244−A single HTTP request. The [$method:http](#method-http) is the HTTP method, the `url` is the unescaped URL, the [$header-list:http](#header-list-http) contains the HTTP headers of the request and the `body` is the actual data. An `octs` is just `[p=@ud q=@]` where `p` is the byte-length of `q`, the data.

243+A single HTTP request. The [$method:http](#methodhttp) is the HTTP method, the `url` is the unescaped URL, the [$header-list:http](#header-listhttp) contains the HTTP headers of the request and the `body` is the actual data. An `octs` is just `[p=@ud q=@]` where `p` is the byte-length of `q`, the data.

245

244

246−## `$response-header:http`

245+### `$response-header:http`

247

246

248```hoon

247```hoon

249+$ response-header

248+$ response-header

@@ -252,9 +251,9 @@ A single HTTP request. The [$method:http](#method-http) is the HTTP method, the

252 ==

251 ==

253```

252```

254

253

255−The status code and [$header-list:http](#header-list-http) of an HTTP response.

254+The status code and [$header-list:http](#header-listhttp) of an HTTP response.

256

255

257−## `$http-event:http`

256+### `$http-event:http`

258

257

259```hoon

258```hoon

260+$ http-event

259+$ http-event

@@ -277,7 +276,7 @@ Urbit treats Earth's HTTP servers as pipes, where Urbit sends or receives one or

277

276

278Calculation of control headers such as `'Content-Length'` or `'Transfer-Encoding'` should be performed at a higher level; this structure is merely for what gets sent to or received from Earth.

277Calculation of control headers such as `'Content-Length'` or `'Transfer-Encoding'` should be performed at a higher level; this structure is merely for what gets sent to or received from Earth.

279

278

280−## `$simple-payload:http`

279+### `$simple-payload:http`

281

280

282```hoon

281```hoon

283+$ simple-payload

282+$ simple-payload

@@ -287,4 +286,4 @@ Calculation of control headers such as `'Content-Length'` or `'Transfer-Encoding

287--

286--

288```

287```

289

288

290−A simple, one-event response used for generators. The [$reponse-header:http](#response-header-http) contains the status code and HTTP headers. The `octs` in the `data` contains the body of the response and is a `[p=@ud q=@]` where `p` is the byte-length of `q`, the data.

289+A simple, one-event response used for generators. The [$reponse-header:http](#response-headerhttp) contains the status code and HTTP headers. The `octs` in the `data` contains the body of the response and is a `[p=@ud q=@]` where `p` is the byte-length of `q`, the data.

content/docs/arvo/eyre/examples.md+29−41

@@ -4,29 +4,17 @@ weight = 6

4template = "doc.html"

5+++

7−# Contents

8−

9−- [Introduction](#introduction)

10−- [Authenticating](#authenticating)

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

12−- [Scrying](#scrying)

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

14−- [Generators](#generators)

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

16−

17−# Introduction

18−

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

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

21−General 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.

9+General 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.

23−# Authenticating

11+## Authenticating

25−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).

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).

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

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

29−Using `curl` in the unix terminal, we'll make an HTTP POST request with `"password=<code>"` in the body:

17+Using `curl` in the unix terminal, we'll make an HTTP POST request with `"password=CODE"` in the body:

31```

19```

32curl -i localhost:8080/~/login -X POST -d "password=lidlut-tabwed-pillex-ridrup"

20curl -i localhost:8080/~/login -X POST -d "password=lidlut-tabwed-pillex-ridrup"

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

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

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.

47−# Using The Channel System

35+## Using The Channel System

49−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.

37+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#channels) section of the [External API Reference](/docs/arvo/eyre/external-api-ref) document for relevant details.

51First, we must obtain a session cookie by [authenticating](#authenticating). You will be copying the entry of the `set-cookie` field into the `--cookie` field in subsequent commands.

39First, we must obtain a session cookie by [authenticating](#authenticating). You will be copying the entry of the `set-cookie` field into the `--cookie` field in subsequent commands.

@@ -54,7 +42,7 @@ Now that we have our cookie, we can try poking an app & simultaneously opening a

55We'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.

43We'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.

57−The data will be a JSON array containing a [poke](@/docs/arvo/eyre/external-api-ref.md#poke) `action`:

45+The data will be a JSON array containing a [poke](/docs/arvo/eyre/external-api-ref#poke) `action`:

59```

47```

60curl --header "Content-Type: application/json" \

48curl --header "Content-Type: application/json" \

@@ -76,7 +64,7 @@ Now we can connect to the `mychannel` channel we opened. We do this with an HTTP

76curl -i --cookie "urbauth-~zod=0v3.j2062.1prp1.qne4e.goq3h.ksudm" http://localhost:8080/~/channel/my-channel

64curl -i --cookie "urbauth-~zod=0v3.j2062.1prp1.qne4e.goq3h.ksudm" http://localhost:8080/~/channel/my-channel

77```

65```

79−Eyre will respond with an HTTP status code of 200 and a `content-type` of `text/event-stream`, indicating an SSE (Server Sent Event) stream. It will also send us any pending events on the channel - in this case the poke ack as a [poke](@/docs/arvo/eyre/external-api-ref.md#poke-ack) `response` for our original poke:

67+Eyre will respond with an HTTP status code of 200 and a `content-type` of `text/event-stream`, indicating an SSE (Server Sent Event) stream. It will also send us any pending events on the channel - in this case the poke ack as a [poke](/docs/arvo/eyre/external-api-ref#poke-ack) `response` for our original poke:

81```

69```

82HTTP/1.1 200 ok

70HTTP/1.1 200 ok

@@ -97,7 +85,7 @@ Normally this event stream would be handled by an EventSource object or similar

98Leaving the event stream connection open, in another shell session on unix we'll try subscribing to the watch path of a Gall agent - the `/updates` watch path of `graph-store` in this case.

86Leaving the event stream connection open, in another shell session on unix we'll try subscribing to the watch path of a Gall agent - the `/updates` watch path of `graph-store` in this case.

100−We'll do this in the same way as the initial poke, except this time it will be a [subscribe](@/docs/arvo/eyre/external-api-ref.md#subscribe) `action`:

88+We'll do this in the same way as the initial poke, except this time it will be a [subscribe](/docs/arvo/eyre/external-api-ref#subscribe) `action`:

101

102```

90```

103curl --header "Content-Type: application/json" \

91curl --header "Content-Type: application/json" \

@@ -109,21 +97,21 @@ curl --header "Content-Type: application/json" \

109

110Notice 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.

98Notice 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.

111

112−Back 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:

100+Back in the event stream, we'll see a positive watch ack as a [subscribe](/docs/arvo/eyre/external-api-ref#watch-ack) `response`, meaning the subscription has been successful:

113

101

114```

102```

115id: 1

103id: 1

116data: {"ok":"ok","id":2,"response":"subscribe"}

104data: {"ok":"ok","id":2,"response":"subscribe"}

117```

105```

118

106

119−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`:

107+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#diff) `response`:

120

108

121```

109```

122id: 2

110id: 2

123data: {"json":{"graph-update":{"add-graph":{"graph":{},"resource":{"name":"test-1183","ship":"zod"},"mark":"graph-validator-chat","overwrite":false}}},"id":2,"response":"diff"}

111data: {"json":{"graph-update":{"add-graph":{"graph":{},"resource":{"name":"test-1183","ship":"zod"},"mark":"graph-validator-chat","overwrite":false}}},"id":2,"response":"diff"}

124```

112```

125

113

126−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:

114+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#ack) `action` which specifies the `event-id` of the event in question - `2` in this case:

127

115

128```

116```

129curl --header "Content-Type: application/json" \

117curl --header "Content-Type: application/json" \

@@ -135,7 +123,7 @@ curl --header "Content-Type: application/json" \

135

123

136This 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.

124This 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.

137

125

138−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:

126+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#unsubscribe) `action`, and specify the request ID of the original `subscribe` `action` in the `subscription` field - `2` in our case:

139

127

140```

128```

141curl --header "Content-Type: application/json" \

129curl --header "Content-Type: application/json" \

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

147

135

148Unlike `poke` and `subscribe` actions, Eyre doesn't acknowledge `unsubscribe`s, but we'll now have stopped receiving updates from `graph-store`.

136Unlike `poke` and `subscribe` actions, Eyre doesn't acknowledge `unsubscribe`s, but we'll now have stopped receiving updates from `graph-store`.

149

137

150−Finally, 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`:

138+Finally, let's close the channel itself. We can do this simply by sending Eyre a [delete](/docs/arvo/eyre/external-api-ref#delete-channel) `action`:

151

139

152```

140```

153curl --header "Content-Type: application/json" \

141curl --header "Content-Type: application/json" \

@@ -159,9 +147,9 @@ curl --header "Content-Type: application/json" \

159

147

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

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

161

149

162−# Scrying

150+## Scrying

163

151

164−Here 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.

152+Here 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.

165

153

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

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

167

155

@@ -213,13 +201,13 @@ content-type: text/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>

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>

214```

202```

215

203

216−# Direct HTTP Handling With Gall Agents

204+## Direct HTTP Handling With Gall Agents

217

205

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.

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

219

207

220−You 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.

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

221

209

222−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.

210+Here's a Gall agent that demonstrates this method. It binds the URL path `/foo`, serves `Hello, World!` for GET requests and a `405` error for all others. It also prints debug information to the terminal as various things happen.

223

211

224Note that this example does a lot of 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.

212Note that this example does a lot of 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.

225

213

@@ -336,7 +324,7 @@ activated app home/eyre-agent

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

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

337```

325```

338

326

339−Now, 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.md#connect) `task` to Eyre when poked with `%bind`:

327+Now, 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`:

340

328

341```hoon

329```hoon

342 %noun

330 %noun

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

436

424

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

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

438

426

439−# Generators

427+## Generators

440

428

441Here 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.

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.

442

430

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

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

444

432

445Here'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`.

433Here'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`.

446

434

@@ -475,7 +463,7 @@ The sample of the second nested gate must be:

475[authenticated=? =request:http]

463[authenticated=? =request:http]

476```

464```

477

465

478−The return type of the generator must be [simple-payload:http](@/docs/arvo/eyre/data-types.md#simple-payload-http). If you look at our example generator you'll see it meets these requirements.

466+The return type of the generator must be [$simple-payload:http](/docs/arvo/eyre/data-types#simple-payloadhttp). If you look at our example generator you'll see it meets these requirements.

479

467

480Because generators return the entire HTTP message as a single `simple-payload`, Eyre can calculate the `content-length` itself and automatically add the header.

468Because generators return the entire HTTP message as a single `simple-payload`, Eyre can calculate the `content-length` itself and automatically add the header.

481

469

@@ -485,7 +473,7 @@ In order to make our generator available, we must bind it to a URL path. To do t

485[%serve =binding =generator]

473[%serve =binding =generator]

486```

474```

487

475

488−The [binding](@/docs/arvo/eyre/data-types.md#binding) specifies the site and URL path, and the [generator](@/docs/arvo/eyre/data-types.md#generator) specifies the `desk`, the `path` to the generator, and arguments. Note that the passing of arguments to the generator by Eyre is not currently implemented, so you can just leave that as `~` since it won't do anything.

476+The [$binding](/docs/arvo/eyre/data-types#binding) specifies the site and URL path, and the [$generator](/docs/arvo/eyre/data-types#generator) specifies the `desk`, the `path` to the generator, and arguments. Note that the passing of arguments to the generator by Eyre is not currently implemented, so you can just leave that as `~` since it won't do anything.

489

477

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

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

491

479

@@ -516,9 +504,9 @@ Content-Length: 41

516blah blah blah

504blah blah blah

517```

505```

518

506

519−# Managing CORS Origins

507+## Managing CORS Origins

520

508

521−Here we'll look at approving and rejecting a CORS origin by passing Clay a [%approve-origin](@/docs/arvo/eyre/tasks.md#approve-origin) `task` and [%reject-origin](@/docs/arvo/eyre/tasks.md#reject-origin) `task` respectively.

509+Here we'll look at approving and rejecting a CORS origin by passing Clay a [%approve-origin](/docs/arvo/eyre/tasks#approve-origin) `task` and [%reject-origin](/docs/arvo/eyre/tasks#reject-origin) `task` respectively.

522

510

523In this example we'll use more manual methods for demonstrative purposes but note there are also the `|cors-approve` and `|cors-reject` generators to approve/reject origins from the dojo, and the `+cors-registry` generator for viewing the CORS configuration.

511In this example we'll use more manual methods for demonstrative purposes but note there are also the `|cors-approve` and `|cors-reject` generators to approve/reject origins from the dojo, and the `+cors-registry` generator for viewing the CORS configuration.

524

512

@@ -528,7 +516,7 @@ First, using `|pass` in the dojo, let's approve the origin `http://foo.example`

528|pass [%e [%approve-origin 'http://foo.example']]

516|pass [%e [%approve-origin 'http://foo.example']]

529```

517```

530

518

531−Now if we scry for the [approved](@/docs/arvo/eyre/scry.md#cors-approved) CORS `set`:

519+Now if we scry for the [approved](/docs/arvo/eyre/scry#cors-approved) CORS `set`:

532

520

533```

521```

534> .^(approved=(set @t) %ex /=//=/cors/approved)

522> .^(approved=(set @t) %ex /=//=/cors/approved)

@@ -566,7 +554,7 @@ Now we'll try rejecting an `origin`. Back in the dojo, let's `|pass` Eyre a `%re

566|pass [%e [%reject-origin 'http://bar.example']]

554|pass [%e [%reject-origin 'http://bar.example']]

567```

555```

568

556

569−If we scry for the [rejected](@/docs/arvo/eyre/scry.md#cors-rejected) CORS `set`:

557+If we scry for the [rejected](/docs/arvo/eyre/scry#cors-rejected) CORS `set`:

570

558

571```

559```

572> .^(rejected=(set @t) %ex /=//=/cors/rejected)

560> .^(rejected=(set @t) %ex /=//=/cors/rejected)

@@ -615,7 +603,7 @@ Connection: close

615Server: urbit/vere-1.5

603Server: urbit/vere-1.5

616```

604```

617

605

618−Now if we scry for the [requests](@/docs/arvo/eyre/scry.md#cors-requests) CORS `set`:

606+Now if we scry for the [requests](/docs/arvo/eyre/scry#cors-requests) CORS `set`:

619

607

620```

608```

621> .^(requests=(set @t) %ex /=//=/cors/requests)

609> .^(requests=(set @t) %ex /=//=/cors/requests)

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

@@ -4,31 +4,9 @@ weight = 2

4template = "doc.html"

5+++

7−# Contents

8−

9−- [Introduction](#introduction)

10−- [Authentication](#authentication)

11−- [Channels](#channels)

12− - [HTTP Requests](#http-requests)

13− - [Actions](#actions)

14− - [Poke](#poke)

15− - [Subscribe](#subscribe)

16− - [Ack](#ack)

17− - [Unsubscribe](#unsubscribe)

18− - [Delete Channel](#delete-channel)

19− - [Responses](#responses)

20− - [Poke Ack](#poke-ack)

21− - [Watch Ack](#watch-ack)

22− - [Diff](#diff)

23− - [Quit](#quit)

24−- [Scry](#scry)

25−- [Spider](#spider)

26−

27−# Introduction

28−

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.

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.

30−

31−# Authentication

9+## Authentication

33To use Eyre's channel system, run threads or perform scries you must first obtain a session cookie by authenticating with the following HTTP request:

11To use Eyre's channel system, run threads or perform scries you must first obtain a session cookie by authenticating with the following HTTP request:

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

36| ----------- | -------------------------------------- | ---------- | ----------------------------------------------------------------------------------- |

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

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

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

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

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

@@ -50,7 +28,7 @@ The `urbauth-{...}` cookie provided must be included in a `cookie` header with a

50cookie: urbauth-~zod=0v4.ilskp.psv00.t09r0.l8rps.3n97v

28cookie: urbauth-~zod=0v4.ilskp.psv00.t09r0.l8rps.3n97v

51```

29```

53−# Channels

31+## Channels

55Eyre's channel system is the primary way of interacting with Gall agents from outside of Urbit.

33Eyre's channel system is the primary way of interacting with Gall agents from outside of Urbit.

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

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

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

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

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.

78−## HTTP Requests

56+### HTTP Requests

80[Actions](#actions) are sent to Eyre in HTTP PUT requests:

58[Actions](#actions) are sent to Eyre in HTTP PUT requests:

@@ -102,7 +80,7 @@ This is for poking a Gall agent.

104

105−**Example**

83+#### Example

106

107```json

85```json

108{

86{

@@ -115,7 +93,7 @@ This is for poking a Gall agent.

115}

93}

116```

94```

117

118−**Response**

96+#### Response

119

120Eyre will send a [poke ack](#poke-ack) as an SSE event on the channel event stream.

98Eyre will send a [poke ack](#poke-ack) as an SSE event on the channel event stream.

121

@@ -131,7 +109,7 @@ This is for subscribing to a watch `path` of a Gall agent.

133

111

134−**Example**

112+#### Example

135

113

136```json

114```json

137{

115{

@@ -143,7 +121,7 @@ This is for subscribing to a watch `path` of a Gall agent.

143}

121}

144```

122```

145

123

146−**Response**

124+#### Response

147

125

148Eyre will send back a [watch ack](#watch-ack). If subscribing was successful, you will also begin receiving any [diff](#diff)s sent by the Gall agent on the specified `path`.

126Eyre will send back a [watch ack](#watch-ack). If subscribing was successful, you will also begin receiving any [diff](#diff)s sent by the Gall agent on the specified `path`.

149

127

@@ -157,7 +135,7 @@ This is for acknowledging an SSE event. If you `ack` one event, you also implici

159

137

160−**Example**

138+#### Example

161

139

162```json

140```json

163{

141{

@@ -167,7 +145,7 @@ This is for acknowledging an SSE event. If you `ack` one event, you also implici

167}

145}

168```

146```

169

147

170−**Response**

148+#### Response

171

149

172Eyre will not respond to an `ack` action.

150Eyre will not respond to an `ack` action.

173

151

@@ -181,7 +159,7 @@ This is for unsubscribing from a Gall agent watch `path` to which you've previou

183

161

184−**Example**

162+#### Example

185

163

186```json

164```json

187{

165{

@@ -191,7 +169,7 @@ This is for unsubscribing from a Gall agent watch `path` to which you've previou

191}

169}

192```

170```

193

171

194−**Response**

172+#### Response

195

173

196Eyre will not respond to an `unsubscribe` action.

174Eyre will not respond to an `unsubscribe` action.

197

175

@@ -204,7 +182,7 @@ This is for deleting the channel itself.

204| `id` | Number | `5` | ID for keeping track of sent messages. |

182| `id` | Number | `5` | ID for keeping track of sent messages. |

206

184

207−**Example**

185+#### Example

208

186

209```json

187```json

210{

188{

@@ -213,7 +191,7 @@ This is for deleting the channel itself.

213}

191}

214```

192```

215

193

216−**Response**

194+#### Response

217

195

218Eyre will not respond to a `delete` action.

196Eyre will not respond to a `delete` action.

219

197

@@ -223,7 +201,7 @@ Eyre will not respond to a `delete` action.

223

201

224This acknowledgement comes in response to a [poke](#poke) action. A poke ack with an `ok` key means the poke succeeded. A poke ack with an `err` key means the poke failed.

202This acknowledgement comes in response to a [poke](#poke) action. A poke ack with an `ok` key means the poke succeeded. A poke ack with an `err` key means the poke failed.

225

203

226−**Positive Poke Ack**

204+#### Positive Poke Ack

227

205

229| ---------- | --------- | ------------- | -------------------------------------------- |

207| ---------- | --------- | ------------- | -------------------------------------------- |

@@ -231,7 +209,7 @@ This acknowledgement comes in response to a [poke](#poke) action. A poke ack wit

231| `id` | Number | `1` | Request ID of the `poke` being acknowledged. |

209| `id` | Number | `1` | Request ID of the `poke` being acknowledged. |

233

211

234−**Example**

212+#### Example

235

213

236```json

214```json

237{

215{

@@ -241,7 +219,7 @@ This acknowledgement comes in response to a [poke](#poke) action. A poke ack wit

241}

219}

242```

220```

243

221

244−**Negative Poke Ack**

222+#### Negative Poke Ack

245

223

247| ---------- | --------- | ---------------- | --------------------------------------------------------------------- |

225| ---------- | --------- | ---------------- | --------------------------------------------------------------------- |

@@ -249,7 +227,7 @@ This acknowledgement comes in response to a [poke](#poke) action. A poke ack wit

249| `id` | Number | `1` | Request ID of the `poke` being acknowledged. |

227| `id` | Number | `1` | Request ID of the `poke` being acknowledged. |

251

229

252−**Example**

230+#### Example

253

231

254```json

232```json

255{

233{

@@ -259,7 +237,7 @@ This acknowledgement comes in response to a [poke](#poke) action. A poke ack wit

259}

237}

260```

238```

261

239

262−**Action Required**

240+#### Action Required

263

241

264You must ack the event.

242You must ack the event.

265

243

@@ -267,7 +245,7 @@ You must ack the event.

267

245

268This acknowledgement comes in response to a [subscribe](#subscribe) action. A watch ack with an `ok` key means the subscription was successful. A watch ack with an `err` key means the subscription failed.

246This acknowledgement comes in response to a [subscribe](#subscribe) action. A watch ack with an `ok` key means the subscription was successful. A watch ack with an `err` key means the subscription failed.

269

247

270−**Positive Watch Ack**

248+#### Positive Watch Ack

271

249

273| ---------- | --------- | ------------- | --------------------------------------------- |

251| ---------- | --------- | ------------- | --------------------------------------------- |

@@ -275,7 +253,7 @@ This acknowledgement comes in response to a [subscribe](#subscribe) action. A wa

275| `id` | Number | `2` | Request ID of the initial `subscribe` action. |

253| `id` | Number | `2` | Request ID of the initial `subscribe` action. |

277

255

278−**Example**

256+#### Example

279

257

280```json

258```json

281{

259{

@@ -285,7 +263,7 @@ This acknowledgement comes in response to a [subscribe](#subscribe) action. A wa

285}

263}

286```

264```

287

265

288−**Negative Watch Ack**

266+#### Negative Watch Ack

289

267

291| ---------- | --------- | ---------------- | --------------------------------------------------------------------- |

269| ---------- | --------- | ---------------- | --------------------------------------------------------------------- |

@@ -293,7 +271,7 @@ This acknowledgement comes in response to a [subscribe](#subscribe) action. A wa

293| `id` | Number | `2` | Request ID of the initial `subscribe` action. |

271| `id` | Number | `2` | Request ID of the initial `subscribe` action. |

295

273

296−**Example**

274+#### Example

297

275

298```json

276```json

299{

277{

@@ -303,7 +281,7 @@ This acknowledgement comes in response to a [subscribe](#subscribe) action. A wa

303}

281}

304```

282```

305

283

306−**Action Required**

284+#### Action Required

307

285

308You must ack the event.

286You must ack the event.

309

287

@@ -317,7 +295,7 @@ All `fact`s sent by a Gall agent on the `path` to which you've subscribed are de

317| `id` | Number | `3` | Request ID of the initial `subscribe` action from earlier. |

295| `id` | Number | `3` | Request ID of the initial `subscribe` action from earlier. |

319

297

320−**Example**

298+#### Example

321

299

322```json

300```json

323{

301{

@@ -327,7 +305,7 @@ All `fact`s sent by a Gall agent on the `path` to which you've subscribed are de

327}

305}

328```

306```

329

307

330−**Action Required**

308+#### Action Required

331

309

332You must [ack](#ack) each `diff` that comes in the event stream.

310You must [ack](#ack) each `diff` that comes in the event stream.

333

311

@@ -340,7 +318,7 @@ A `quit` comes in when a subscription has been ended. You may be intentionally k

340| `id` | Number | `4` | Request ID of the initial `subscribe` action. |

318| `id` | Number | `4` | Request ID of the initial `subscribe` action. |

342

320

343−**Example**

321+#### Example

344

322

345```json

323```json

346{

324{

@@ -349,11 +327,11 @@ A `quit` comes in when a subscription has been ended. You may be intentionally k

349}

327}

350```

328```

351

329

352−**Action Required**

330+#### Action Required

353

331

354You must ack the event and you may wish to try and re[subscribe](#subscribe).

332You must ack the event and you may wish to try and re[subscribe](#subscribe).

355

333

356−# Scry

334+## Scry

357

335

358A scry is a read-only request for some data.

336A scry is a read-only request for some data.

359

337

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

374

352

375If 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.

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.

376

354

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

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

378

356

379−# Spider

357+## Spider

380

358

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

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

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

@@ -8,54 +8,54 @@ Eyre is the webserver vane.

9HTTP messages come in from outside and Eyre produces HTTP messages in response. In general, apps do not call Eyre; rather, Eyre calls apps. Eyre has a number of ways to handle such HTTP requests which we'll briefly describe.

11−# Authentication

11+## Authentication

13−Most types of requests require the client provide a valid session cookie which is obtained by authenticating with your ship's web login code. Authentication is documented in the [Authentication](@/docs/arvo/eyre/external-api-ref.md#authentication) section of the [External API Reference](@/docs/arvo/eyre/external-api-ref.md) documentation.

13+Most types of requests require the client provide a valid session cookie which is obtained by authenticating with your ship's web login code. Authentication is documented in the [Authentication](/docs/arvo/eyre/external-api-ref#authentication) section of the [External API Reference](/docs/arvo/eyre/external-api-ref) documentation.

15−# The Channel System

15+## The Channel System

17Eyre's channel system is the primary way of interacting with Gall agents from outside of Urbit. It provides a simple JSON API that allows you to send data to apps and subscribe for updates from apps. Updates come back on a SSE ([Server Sent Event](https://html.spec.whatwg.org/#server-sent-events)) stream which you can easily handle with an EventSource object in Javascript or the equivalent in whichever language you prefer.

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.md) document with corresponding examples in the [Examples](@/docs/arvo/eyre/examples.md#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 [Examples](/docs/arvo/eyre/examples#using-the-channel-system) document.

23−# Scrying

23+## Scrying

25Along with the channel system, Eyre also provides a way to make read-only requests for data which are called scries. Eyre's scry interface is separate to the channel system but may be useful in conjunction with it.

27−Details of Eyre's scry API are in the [Scry](@/docs/arvo/eyre/external-api-ref.md#scry) section of the [External API Reference](@/docs/arvo/eyre/external-api-ref.md) document.

27+Details of Eyre's scry API are in the [Scry](/docs/arvo/eyre/external-api-ref#scry) section of the [External API Reference](/docs/arvo/eyre/external-api-ref) document.

29−# Spider Threads

29+## Spider Threads

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.

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) is not part of Eyre proper, so is documented separately in the [Threads](/docs/userspace/threads/overview) documentation.

33−# Generators

33+## Generators

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.md#serve) section of the [Internal API Reference](@/docs/arvo/eyre/tasks.md) documentation and a practical example is provided in the [Generators](@/docs/arvo/eyre/examples.md#generators) section of the [Examples](@/docs/arvo/eyre/examples.md) 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/examples#generators) section of the [Examples](/docs/arvo/eyre/examples) document.

39−# Direct HTTP Handling With Gall Agents

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.md#connect) section of the [Internal API Reference](@/docs/arvo/eyre/tasks.md) document and a detailed example is provided in the [Direct HTTP Handling With Gall Agents](@/docs/arvo/eyre/examples.md#direct-http-handling-with-gall-agents) section of the [Examples](@/docs/arvo/eyre/examples.md) 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 [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.

45−# Cross-Origin Resource Sharing

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.md) to [approve](@/docs/arvo/eyre/tasks.md#approve-origin) and [reject](@/docs/arvo/eyre/tasks.md#reject-origin) origins programmatically, and a number of [scry endpoints](@/docs/arvo/eyre/scry.md) to query them. Examples are also included in the [Managing CORS Origins](@/docs/arvo/eyre/examples.md#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/examples#managing-cors-origins) section of the Examples document.

51−# Eyre Documentation Sections

51+## Sections

53−- [External API Reference](@/docs/arvo/eyre/external-api-ref.md) - Details of Eyre's external API including the channel system's JSON API.

53+[External API Reference](/docs/arvo/eyre/external-api-ref) - Details of Eyre's external API including the channel system's JSON API.

55−- [Internal API Reference](@/docs/arvo/eyre/tasks.md) - The `task`s Eyre takes and the `gift`s it returns.

55+[Internal API Reference](/docs/arvo/eyre/tasks) - The `task`s Eyre takes and the `gift`s it returns.

57−- [Scry Reference](@/docs/arvo/eyre/scry.md) - The scry endpoints of Eyre.

57+[Scry Reference](/docs/arvo/eyre/scry) - The scry endpoints of Eyre.

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

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

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

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

content/docs/arvo/eyre/scry.md+31−49

@@ -4,35 +4,17 @@ weight = 4

4template = "doc.html"

5+++

7−## Contents

8−

9−- [Introduction](#introduction)

10−- [/cors](#cors) - CORS settings.

11− - [/cors/requests](#cors-requests) - Requested origins.

12− - [/cors/approved](#cors-approved) - Approved origins.

13− - [/cors/approved/\<origin\>](#cors-approved-origin) - Check if origin approved.

14− - [/cors/rejected](#cors-rejected) - Rejected origins.

15− - [/cors/rejected/\<origin\>](#cors-rejected-origin) - Check if origin rejected.

16−- [/authenticated/cookie/\<cookie\>](#authenticated-cookie-cookie) - Check if cookie authenticated.

17−- [bindings](#bindings) - URL path bindings.

18−- [connections](#connections) - Open http connections.

19−- [authentication-state](#authentication-state) - Authentication details.

20−- [channel-state](#channel-state) - Details of each channel.

21−- [host](#host) - Host details.

22−

23−# Introduction

24−

25Here are all of Eyre's scry endpoints. There's not too many and they mostly deal with either CORS settings or aspects of the state of connections.

7Here are all of Eyre's scry endpoints. There's not too many and they mostly deal with either CORS settings or aspects of the state of connections.

27−The first few have a `care` of `x` and are a scry like `.^(<type> %ex /=//=/<some-path>)` (note the empty `desk`). The rest have no `care` and the tag replaces the `desk` like `.^(<type> %e /=<something>=)`.

9+The first few have a `care` of `x` and are a scry like `.^({TYPE} %ex /=//=/{SOME-PATH})` (note the empty `desk`). The rest have no `care` and the tag replaces the `desk` like `.^({TYPE} %e /={SOMETHING}=)`.

29All examples are run from the dojo.

11All examples are run from the dojo.

31−# `/cors`

13+## `/cors`

33−An `x` scry with a `path` of `/cors` will return Eyre's CORS origin registry. The type returned is a [cors-registry](@/docs/arvo/eyre/data-types.md#cors-registry) which contains the `set`s of approved, rejected and requested origins.

15+An `x` scry with a `path` of `/cors` will return Eyre's CORS origin registry. The type returned is a [cors-registry](/docs/arvo/eyre/data-types#cors-registry) which contains the `set`s of approved, rejected and requested origins.

35−Example:

17+### Example

37```

19```

38> .^(cors-registry:eyre %ex /=//=/cors)

20> .^(cors-registry:eyre %ex /=//=/cors)

@@ -46,7 +28,7 @@ Example:

47An `x` scry with a `path` of `/cors/requests` will return the `set` of pending origin requests. These are origins that were in an `Origin: ...` HTTP header but weren't in the existing approved or rejected sets. The type returned is a `(set origin:eyre)`.

29An `x` scry with a `path` of `/cors/requests` will return the `set` of pending origin requests. These are origins that were in an `Origin: ...` HTTP header but weren't in the existing approved or rejected sets. The type returned is a `(set origin:eyre)`.

49−Example:

31+### Example

51```

33```

52> .^(requests=(set origin:eyre) %ex /=//=/cors/requests)

34> .^(requests=(set origin:eyre) %ex /=//=/cors/requests)

@@ -57,20 +39,20 @@ requests={~~http~3a.~2f.~2f.baz~.example}

58An `x` scry with a `path` of `/cors/approved` will return the `set` of approved CORS origins. The type returned is a `(set origin:eyre)`.

40An `x` scry with a `path` of `/cors/approved` will return the `set` of approved CORS origins. The type returned is a `(set origin:eyre)`.

60−Example:

42+### Example

62```

44```

63> .^(approved=(set origin:eyre) %ex /=//=/cors/approved)

45> .^(approved=(set origin:eyre) %ex /=//=/cors/approved)

64approved={~~http~3a.~2f.~2f.foo~.example}

46approved={~~http~3a.~2f.~2f.foo~.example}

65```

47```

67−## `/cors/approved/<origin>`

49+## `/cors/approved/{ORIGIN}`

69−An `x` scry whose `path` is `/cors/approved/<origin>` tests whether the given origin URL is in the `approved` set of the CORS registry. The type returned is a simple `?`.

51+An `x` scry whose `path` is `/cors/approved/{ORIGIN}` tests whether the given origin URL is in the `approved` set of the CORS registry. The type returned is a simple `?`.

71The origin URL is a `@t`, but since `@t` may not be valid in a path, it must be encoded in a `@ta` using `+scot` like `(scot %t 'foo')` rather than just `'foo'`.

53The origin URL is a `@t`, but since `@t` may not be valid in a path, it must be encoded in a `@ta` using `+scot` like `(scot %t 'foo')` rather than just `'foo'`.

73−Examples:

55+### Examples

75```

57```

76> .^(? %ex /=//=/cors/approved/(scot %t 'http://foo.example'))

58> .^(? %ex /=//=/cors/approved/(scot %t 'http://foo.example'))

@@ -86,20 +68,20 @@ Examples:

87An `x` scry with a `path` of `/cors/rejected` will return the `set` of rejected CORS origins. The type returned is a `(set origin:eyre)`.

69An `x` scry with a `path` of `/cors/rejected` will return the `set` of rejected CORS origins. The type returned is a `(set origin:eyre)`.

89−Example:

71+### Example

91```

73```

92> .^(rejected=(set origin:eyre) %ex /=//=/cors/rejected)

74> .^(rejected=(set origin:eyre) %ex /=//=/cors/rejected)

93rejected={~~http~3a.~2f.~2f.bar~.example}

75rejected={~~http~3a.~2f.~2f.bar~.example}

94```

76```

96−## `/cors/rejected/<origin>`

78+## `/cors/rejected/{ORIGIN}`

98−An `x` scry whose `path` is `/cors/rejected/<origin>` tests whether the given origin URL is in the `rejected` set of the CORS registry. The type returned is a simple `?`.

80+An `x` scry whose `path` is `/cors/rejected/{ORIGIN}` tests whether the given origin URL is in the `rejected` set of the CORS registry. The type returned is a simple `?`.

100The origin URL must be a cord-encoded `@t` rather than just the plain `@t`, so you'll have to do something like `(scot %t 'foo')` rather than just `'foo'`.

82The origin URL must be a cord-encoded `@t` rather than just the plain `@t`, so you'll have to do something like `(scot %t 'foo')` rather than just `'foo'`.

101

102−Examples:

84+### Examples

103

104```

86```

105> .^(? %ex /=//=/cors/rejected/(scot %t 'http://bar.example'))

87> .^(? %ex /=//=/cors/rejected/(scot %t 'http://bar.example'))

@@ -111,13 +93,13 @@ Examples:

111%.n

93%.n

112```

94```

113

114−# `/authenticated/cookie/<cookie>`

96+## `/authenticated/cookie`

115

116−An `x` scry whose `path` is `/authenticated/cookies/<cookie>` tests whether the given cookie is currently valid. The type returned is a `?`.

98+An `x` scry whose `path` is `/authenticated/cookie/{COOKIE}` tests whether the given cookie is currently valid. The type returned is a `?`.

117

118−The cookie must be the full cookie including the `urbauth-<ship>=` part. The cookie must be a cord-encoded `@t` rather than just a plain `@t`, so you'll have to do something like `(scot %t 'foo')` rather than just `'foo'`.

100+The cookie must be the full cookie including the `urbauth-{SHIP}=` part. The cookie must be a cord-encoded `@t` rather than just a plain `@t`, so you'll have to do something like `(scot %t 'foo')` rather than just `'foo'`.

119

101

120−Examples:

102+### Examples

121

103

122```

104```

123> .^(? %ex /=//=/authenticated/cookie/(scot %t 'urbauth-~zod=0vvndn8.bfsjj.j3614.k40ha.8fomi'))

105> .^(? %ex /=//=/authenticated/cookie/(scot %t 'urbauth-~zod=0vvndn8.bfsjj.j3614.k40ha.8fomi'))

@@ -129,11 +111,11 @@ Examples:

129%.n

111%.n

130```

112```

131

113

132−# `bindings`

114+## `%bindings`

133

115

134−A scry with `bindings` in place of the `desk` in the `beak` will return Eyre's URL path bindings. The type returned is a `(list [binding:eyre duct action:eyre])` (see the [binding](@/docs/arvo/eyre/data-types.md#binding) & [action](@/docs/arvo/eyre/data-types.md#action) sections of the Data Types document for details).

116+A scry with `bindings` in place of the `desk` in the `beak` will return Eyre's URL path bindings. The type returned is a `(list [binding:eyre duct action:eyre])` (see the [$binding](/docs/arvo/eyre/data-types#binding) & [$action](/docs/arvo/eyre/data-types#action) sections of the Data Types document for details).

135

117

136−Example:

118+### Example

137

119

138```

120```

139> .^((list [binding:eyre duct action:eyre]) %e /=bindings=)

121> .^((list [binding:eyre duct action:eyre]) %e /=bindings=)

@@ -150,22 +132,22 @@ Example:

150]

132]

151```

133```

152

134

153−# `connections`

135+## `%connections`

154

136

155−A scry with `bindings` in place of the `desk` in the `beak` will return all open HTTP connections that aren't fully complete. The type returned is a `(map duct outstanding-connection:eyre)` (see the [outstanding-connection](@/docs/arvo/eyre/data-types.md#outstanding-connection) section of the Data Types document for details).

137+A scry with `bindings` in place of the `desk` in the `beak` will return all open HTTP connections that aren't fully complete. The type returned is a `(map duct outstanding-connection:eyre)` (see the [$outstanding-connection](/docs/arvo/eyre/data-types#outstanding-connection) section of the Data Types document for details).

156

138

157−Example:

139+### Example

158

140

159```

141```

160> .^((map duct outstanding-connection:eyre) %e /=connections=)

142> .^((map duct outstanding-connection:eyre) %e /=connections=)

161{}

143{}

162```

144```

163

145

164−# `authentication-state`

146+## `%authentication-state`

165

147

166−A scry with `authentication-state` in place of the `desk` in the `beak` will return authentication details of all current sessions. The type returned is a [authentication-state](@/docs/arvo/eyre/data-types.md#authentication-state). The `p` field is the cookie sans the `urbauth-<ship>=` part.

148+A scry with `authentication-state` in place of the `desk` in the `beak` will return authentication details of all current sessions. The type returned is a [$authentication-state](/docs/arvo/eyre/data-types#authentication-state). The `p` field is the cookie sans the `urbauth-{SHIP}=` part.

167

149

168−Example:

150+### Example

169

151

170```

152```

171> .^(authentication-state:eyre %e /=authentication-state=)

153> .^(authentication-state:eyre %e /=authentication-state=)

@@ -176,11 +158,11 @@ Example:

176}

158}

177```

159```

178

160

179−# `channel-state`

161+## `%channel-state`

180

162

181−A scry with `channel-state` in place of the `desk` in the `beak` will return details of the state of each channel. The type returned is a [channel-state](@/docs/arvo/eyre/data-types.md#channel-state).

163+A scry with `channel-state` in place of the `desk` in the `beak` will return details of the state of each channel. The type returned is a [channel-state](/docs/arvo/eyre/data-types#channel-state).

182

164

183−Example:

165+### Example

184

166

185```

167```

186> .^(channel-state:eyre %e /=channel-state=)

168> .^(channel-state:eyre %e /=channel-state=)

@@ -201,11 +183,11 @@ Example:

201]

183]

202```

184```

203

185

204−# `host`

186+## `%host`

205

187

206A scry with `host` in place of the `desk` in the `beak` will return host details of the ship. The type returned is a `hart:eyre`.

188A scry with `host` in place of the `desk` in the `beak` will return host details of the ship. The type returned is a `hart:eyre`.

207

189

208−Example:

190+### Example

209

191

210```

192```

211> .^(hart:eyre %e /=host=)

193> .^(hart:eyre %e /=host=)

content/docs/arvo/eyre/tasks.md+43−60

@@ -4,30 +4,13 @@ weight = 3

4template = "doc.html"

5+++

7−# Contents

8−

9−- [Introduction](#introduction)

10−- [%live](#live) - _(Internal only)_ - Notifies Eyre of HTTP(S) ports.

11−- [%rule](#rule) - _(Usually internal)_ - Sets TLS cert or DNS binding.

12−- [%request](#request) - _(Internal only)_ - Incoming HTTP request.

13−- [%request-local](#request-local) - _(Internal only)_ - Incoming HTTP request from the local loopback port.

14−- [%cancel-request](#cancel-request) - _(Internal only)_ - Notifies Eyre of a connection being closed externally.

15−- [%connect](#connect) - Bind a Gall agent to a URL.

16−- [%serve](#serve) - Bind a generator to a URL.

17−- [%disconnect](#disconnect) - Disconnect agent or generator from URL binding.

18−- [%code-changed](#code-changed) - _(Usually internal)_ - Notifies Eyre of the web login code changing.

19−- [%approve-origin](#approve-origin) - Approve a CORS origin.

20−- [%reject-origin](#reject-origin) - Reject a CORS origin.

21−

22−# Introduction

23−

24This 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.

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.

26−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.md) 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 [Examples](/docs/arvo/eyre/examples) document. The rest are just documented for completeness.

28−Many of the types referenced are detailed in the [Data Types](@/docs/arvo/eyre/data-types.md) 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.

11+Many 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.

30−# `%live`

13+## `%live`

32```hoon

15```hoon

33[%live insecure=@ud secure=(unit @ud)]

16[%live insecure=@ud secure=(unit @ud)]

@@ -37,11 +20,11 @@ This `task` notifies Eyre of the listening HTTPS and HTTP ports. It is automatic

38The `insecure` field is the HTTP port and `secure` is the optional HTTPS port.

21The `insecure` field is the HTTP port and `secure` is the optional HTTPS port.

40−## Returns

23+### Returns

42Eyre returns no `gift` in response to a `%live` `task`.

25Eyre returns no `gift` in response to a `%live` `task`.

44−# `%rule`

27+## `%rule`

46```hoon

29```hoon

47[%rule =http-rule]

30[%rule =http-rule]

@@ -49,13 +32,13 @@ Eyre returns no `gift` in response to a `%live` `task`.

50This `task` either configures HTTPS with a certificate and keypair, or configures a DNS binding. This is typically done for you by the `%acme` app, rather than done manually.

33This `task` either configures HTTPS with a certificate and keypair, or configures a DNS binding. This is typically done for you by the `%acme` app, rather than done manually.

52−The [http-rule](@/docs/arvo/eyre/data-types.md#http-rule) is either tagged with `%cert` or `%turf`. A `%cert` `http-rule` sets an HTTPS certificate and keypair or removes it if null. A `%turf` `http-rule` either adds or removes a DNS binding depending on whether the `action` is `%put` or `%del`. Note that using `%turf` will automatically cause the system to try and obtain a certificate and keypair via Letsencrypt.

35+The [$http-rule](/docs/arvo/eyre/data-types#http-rule) is either tagged with `%cert` or `%turf`. A `%cert` `http-rule` sets an HTTPS certificate and keypair or removes it if null. A `%turf` `http-rule` either adds or removes a DNS binding depending on whether the `action` is `%put` or `%del`. Note that using `%turf` will automatically cause the system to try and obtain a certificate and keypair via Letsencrypt.

54−## Returns

37+### Returns

56Eyre returns no `gift` in response to a `%rule` `task`.

39Eyre returns no `gift` in response to a `%rule` `task`.

58−# `%request`

41+## `%request`

60```hoon

43```hoon

61[%request secure=? =address =request:http]

44[%request secure=? =address =request:http]

@@ -63,13 +46,13 @@ Eyre returns no `gift` in response to a `%rule` `task`.

64This `task` is how Eyre receives an inbound HTTP request. It will ordinarily be sent to Eyre by the runtime so you wouldn't use it except perhaps in tests.

47This `task` is how Eyre receives an inbound HTTP request. It will ordinarily be sent to Eyre by the runtime so you wouldn't use it except perhaps in tests.

66−The `secure` field says whether it's over HTTPS. The `address` is the IP address from which the request originated. The [request:http](@/docs/arvo/eyre/data-types.md#request-http) is the HTTP request itself containing the method, URL, headers, and body.

49+The `secure` field says whether it's over HTTPS. The `address` is the IP address from which the request originated. The [$request:http](/docs/arvo/eyre/data-types#requesthttp) is the HTTP request itself containing the method, URL, headers, and body.

68−## Returns

51+### Returns

70Eyre may `pass` a `%response` `gift` on the appropriate `duct` depending on the contents of the `%request`, state of the connection, and other factors.

53Eyre may `pass` a `%response` `gift` on the appropriate `duct` depending on the contents of the `%request`, state of the connection, and other factors.

72−# `%request-local`

55+## `%request-local`

74```hoon

57```hoon

75[%request-local secure=? =address =request:http]

58[%request-local secure=? =address =request:http]

@@ -77,11 +60,11 @@ Eyre may `pass` a `%response` `gift` on the appropriate `duct` depending on the

78This `task` is how Eyre receives an inbound HTTP request over the local loopback port. It behaves the same and takes the same arguments as in the [%request](#request) example except it skips any normally required authentication. Just like for a [%request](#request) `task`, you'd not normally use this manually.

61This `task` is how Eyre receives an inbound HTTP request over the local loopback port. It behaves the same and takes the same arguments as in the [%request](#request) example except it skips any normally required authentication. Just like for a [%request](#request) `task`, you'd not normally use this manually.

80−## Returns

63+### Returns

82Eyre may `pass` a `%response` `gift` on the appropriate `duct` depending on the contents of the `%request`, state of the connection, and other factors.

65Eyre may `pass` a `%response` `gift` on the appropriate `duct` depending on the contents of the `%request`, state of the connection, and other factors.

84−# `%cancel-request`

67+## `%cancel-request`

86```hoon

69```hoon

87[%cancel-request ~]

70[%cancel-request ~]

@@ -91,11 +74,11 @@ This `task` is sent to Eyre by the runtime when an HTTP client closes its previo

92This `task` takes no arguments.

75This `task` takes no arguments.

94−## Returns

77+### Returns

96Eyre may `pass` a `%response` `gift` on the appropriate `duct` depending on the state of the connection and other factors.

79Eyre may `pass` a `%response` `gift` on the appropriate `duct` depending on the state of the connection and other factors.

98−# `%connect`

81+## `%connect`

100```hoon

83```hoon

101[%connect =binding app=term]

84[%connect =binding app=term]

@@ -103,19 +86,19 @@ Eyre may `pass` a `%response` `gift` on the appropriate `duct` depending on the

103

104This `task` binds a Gall agent to a URL path so it can receive HTTP requests and return HTTP responses directly.

87This `task` binds a Gall agent to a URL path so it can receive HTTP requests and return HTTP responses directly.

105

106−The [binding](@/docs/arvo/eyre/data-types.md#binding) contains a URL path and optional domain through which the agent will be able to take HTTP requests. The `app` is just the name of the Gall agent to bind. Note that if you bind a URL path of `/foo`, Eyre will also match `/foo/bar`, `/foo/bar/baz`, etc.

89+The [$binding](/docs/arvo/eyre/data-types#binding) contains a URL path and optional domain through which the agent will be able to take HTTP requests. The `app` is just the name of the Gall agent to bind. Note that if you bind a URL path of `/foo`, Eyre will also match `/foo/bar`, `/foo/bar/baz`, etc.

107

108−If an agent is bound in Eyre using this method, HTTP requests to the bound URL path are poked directly into the agent. The `cage` in the poke have a `%handle-http-request` `mark` and a `vase` of `[@ta inbound-request:eyre]` where the `@ta` is a unique `eyre-id` and the [inbound-request](@/docs/arvo/eyre/data-types.md#inbound-request) contains the HTTP request itself.

91+If an agent is bound in Eyre using this method, HTTP requests to the bound URL path are poked directly into the agent. The `cage` in the poke have a `%handle-http-request` `mark` and a `vase` of `[@ta inbound-request:eyre]` where the `@ta` is a unique `eyre-id` and the [$inbound-request](/docs/arvo/eyre/data-types#inbound-request) contains the HTTP request itself.

109

110Along with the poke, Eyre will also subscribe to the `/http-response/[eyre-id]` `path` of the agent and await a response, which it will pass on to the HTTP client who made the request. Eyre expects at least two `fact`s and a `kick` on this subscription path to complete the response and close the connection (though it can take more than two `fact`s).

93Along with the poke, Eyre will also subscribe to the `/http-response/[eyre-id]` `path` of the agent and await a response, which it will pass on to the HTTP client who made the request. Eyre expects at least two `fact`s and a `kick` on this subscription path to complete the response and close the connection (though it can take more than two `fact`s).

111

112−The first `fact`'s `cage` must have a `mark` of `%http-response-header` and a `vase` containing a [response-header:http](@/docs/arvo/eyre/data-types.md#response-header-http) with the HTTP status code and headers of the response.

95+The first `fact`'s `cage` must have a `mark` of `%http-response-header` and a `vase` containing a [$response-header:http](/docs/arvo/eyre/data-types#response-headerhttp) with the HTTP status code and headers of the response.

113

114The `cage` of the second and subsequent `fact`s must have a `mark` of `%http-response-data` and a `vase` containing a `(unit octs)` with the actual data of the response. An `octs` is just `[p=@ud q=@]` where `p` is the byte-length of `q`, the data. You can send an arbitrary number of these.

97The `cage` of the second and subsequent `fact`s must have a `mark` of `%http-response-data` and a `vase` containing a `(unit octs)` with the actual data of the response. An `octs` is just `[p=@ud q=@]` where `p` is the byte-length of `q`, the data. You can send an arbitrary number of these.

115

116Finally, once you've sent all the `fact`s you want, you can `kick` Eyre's subscription and it will complete the response and close the connection to the HTTP client.

99Finally, once you've sent all the `fact`s you want, you can `kick` Eyre's subscription and it will complete the response and close the connection to the HTTP client.

117

100

118−## Returns

101+### Returns

119

102

120Eyre will respond with a `%bound` `gift` which says whether the binding was successful and looks like:

103Eyre will respond with a `%bound` `gift` which says whether the binding was successful and looks like:

121

104

@@ -125,11 +108,11 @@ Eyre will respond with a `%bound` `gift` which says whether the binding was succ

125

108

126The `accepted` field says whether the binding succeeded and the `binding` is the requested binding described above.

109The `accepted` field says whether the binding succeeded and the `binding` is the requested binding described above.

127

110

128−## Example

111+### Example

129

112

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

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.

131

114

132−# `%serve`

115+## `%serve`

133

116

134```hoon

117```hoon

135[%serve =binding =generator]

118[%serve =binding =generator]

@@ -137,9 +120,9 @@ See the [Direct HTTP Handling With Gall Agents](@/docs/arvo/eyre/examples.md#dir

137

120

138This `task` binds a generator to a URL path so it can receive HTTP requests and return HTTP responses.

121This `task` binds a generator to a URL path so it can receive HTTP requests and return HTTP responses.

139

122

140−The `binding` contains the URL path and optional domain through which the generator will take HTTP requests. The [generator](@/docs/arvo/eyre/data-types.md#generator) specifies the `desk`, the `path` to the generator in Clay, and also has a field for arguments. Note that the passing of specified arguments to the generator by Eyre is not currently implemented, so you can just leave it as `~`.

123+The `binding` contains the URL path and optional domain through which the generator will take HTTP requests. The [$generator](/docs/arvo/eyre/data-types#generator) specifies the `desk`, the `path` to the generator in Clay, and also has a field for arguments. Note that the passing of specified arguments to the generator by Eyre is not currently implemented, so you can just leave it as `~`.

141

124

142−The bound generator must be a gate within a gate and the type returned must be a [simple-payload:http](@/docs/arvo/eyre/data-types.md#simple-payload-http).

125+The bound generator must be a gate within a gate and the type returned must be a [$simple-payload:http](/docs/arvo/eyre/data-types#simple-payloadhttp).

143

126

144The sample of the first gate must be:

127The sample of the first gate must be:

145

128

@@ -153,19 +136,19 @@ The sample of the first gate must be:

153[authenticated=? =request:http]

136[authenticated=? =request:http]

154```

137```

155

138

156−The `?` says whether the HTTP request contained a valid session cookie and the [request:http](@/docs/arvo/eyre/data-types.md#request-http) contains the request itself.

139+The `?` says whether the HTTP request contained a valid session cookie and the [$request:http](/docs/arvo/eyre/data-types#requesthttp) contains the request itself.

157

140

158The `simple-payload:http` returned by the generator is similar to the response described in the [%connect](#connect) section except the HTTP headers and body are all contained in the one response rather than staggered across several.

141The `simple-payload:http` returned by the generator is similar to the response described in the [%connect](#connect) section except the HTTP headers and body are all contained in the one response rather than staggered across several.

159

142

160−## Returns

143+### Returns

161

144

162Eyre will return a `%bound` `gift` as described at the end of the [%connect](#connect) section.

145Eyre will return a `%bound` `gift` as described at the end of the [%connect](#connect) section.

163

146

164−## Example

147+### Example

165

148

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

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

167

150

168−# `%disconnect`

151+## `%disconnect`

169

152

170```hoon

153```hoon

171[%disconnect =binding]

154[%disconnect =binding]

@@ -173,13 +156,13 @@ See the [Generators](@/docs/arvo/eyre/examples.md#generators) section of the [Ex

173

156

174This `task` deletes a URL binding previously set by a `%connect` or `%serve` `task`.

157This `task` deletes a URL binding previously set by a `%connect` or `%serve` `task`.

175

158

176−The [binding](@/docs/arvo/eyre/data-types.md#binding) is the URL path and domain of the binding you want to delete.

159+The [$binding](/docs/arvo/eyre/data-types#binding) is the URL path and domain of the binding you want to delete.

177

160

178−## Returns

161+### Returns

179

162

180Eyre returns no `gift` in response to a `%disconnect` `task`.

163Eyre returns no `gift` in response to a `%disconnect` `task`.

181

164

182−# `%code-changed`

165+## `%code-changed`

183

166

184```hoon

167```hoon

185[%code-changed ~]

168[%code-changed ~]

@@ -189,11 +172,11 @@ This `task` tells Eyre that the web login code has changed, causing Eyre to thro

189

172

190This `task` takes no arguments.

173This `task` takes no arguments.

191

174

192−## Returns

175+### Returns

193

176

194Eyre returns no `gift` in response to a `%code-changed` `task`.

177Eyre returns no `gift` in response to a `%code-changed` `task`.

195

178

196−# `%approve-origin`

179+## `%approve-origin`

197

180

198```hoon

181```hoon

199[%approve-origin =origin]

182[%approve-origin =origin]

@@ -201,17 +184,17 @@ Eyre returns no `gift` in response to a `%code-changed` `task`.

201

184

202This `task` tells Eyre to start responding positively to CORS requests for the specified `origin`.

185This `task` tells Eyre to start responding positively to CORS requests for the specified `origin`.

203

186

204−The [origin](@/docs/arvo/eyre/data-types.md#origin) is a CORS origin like `http://foo.example` you want to approve.

187+The [$origin](/docs/arvo/eyre/data-types#origin) is a CORS origin like `http://foo.example` you want to approve.

205

188

206−## Returns

189+### Returns

207

190

208Eyre returns no `gift` in response to a `%approve-origin` `task`.

191Eyre returns no `gift` in response to a `%approve-origin` `task`.

209

192

210−## Example

193+### Example

211

194

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

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.

213

196

214−# `%reject-origin`

197+## `%reject-origin`

215

198

216```hoon

199```hoon

217[%reject-origin =origin]

200[%reject-origin =origin]

@@ -219,12 +202,12 @@ See the [Managing CORS Origins](@/docs/arvo/eyre/examples.md#managing-cors-origi

219

202

220This `task` tells Eyre to start responding negatively to CORS requests for the specified `origin`.

203This `task` tells Eyre to start responding negatively to CORS requests for the specified `origin`.

221

204

222−The [origin](@/docs/arvo/eyre/data-types.md#origin) is a CORS origin like `http://foo.example` you want want to reject.

205+The [$origin](/docs/arvo/eyre/data-types#origin) is a CORS origin like `http://foo.example` you want want to reject.

223

206

224−## Returns

207+### Returns

225

208

226Eyre returns no `gift` in response to a `%reject-origin` `task`.

209Eyre returns no `gift` in response to a `%reject-origin` `task`.

227

210

228−## Example

211+### Example

229

212

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

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.