43afac9 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

api ref & types docs fixes as per @Fang- comments

43afac9tinnus-napbus5 years ago

arvo/eyre/data-types.md+4−4

compare with master

unifiedsplit

@@ -44,7 +44,7 @@ CORS origins categorised by approval status. The `requests` `set` contains all [

44 ==

45```

47−An 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 of the initial response. The `bytes-sent` is the total bytes sent so far in response.

47+An 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`

@@ -201,7 +201,7 @@ A client IP address.

201 ==

202```

203

204−An inbound HTTP request and metadata - this is what comes in when an external client makes a request to Eyre. 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 client's IP address. The [$request:http](#request-http) contains the HTTP request itself.

204+An inbound HTTP request and metadata - this is what is poked into a bound app. 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 client's IP address. The [$request:http](#request-http) contains the HTTP request itself.

205

206# HTTP

207

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

252 ==

253```

254

255−The status code and [$header-list:http](#header-list-http) of an HTTP response. This is typically sent separately to the body.

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

256

257## `$http-event:http`

258

@@ -273,7 +273,7 @@ The status code and [$header-list:http](#header-list-http) of an HTTP response.

273

274Packetized HTTP.

275

276−Urbit treats Earth's HTTP servers as pipes, where Urbit sends or receives one or more `http-event`s. The first of these will always be a `%start` or an `%error`, and the last will always be `%cancel` or will have `complete` set to `%.y` to finish the connection.

276+Urbit treats Earth's HTTP servers as pipes, where Urbit sends or receives one or more `http-event`s. The first of these will be a `%start`, and the last will always be `%cancel` or will have `complete` set to `%.y` to finish the connection.

277

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.

279

arvo/eyre/external-api-ref.md+21−21

@@ -19,8 +19,8 @@ template = "doc.html"

19 - [Responses](#responses)

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

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

22− - [Fact](#fact)

22+ - [Diff](#diff)

23− - [Kick](#kick)

23+ - [Quit](#quit)

24- [Scry](#scry)

25- [Spider](#spider)

@@ -65,7 +65,7 @@ id: 0

65data: {"ok":"ok","id":1,"response":"poke"}

66```

68−If you're working with Javascript in the browser context you'll handle these with an EventSource object. If you're using another language, there'll likely be a library available to handle SSEs.

68+If you're working with Javascript in the browser context you'll handle these with an EventSource object or by using fetch and ReadableStream. If you're using another language, there'll likely be a library available to handle SSEs.

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

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

93|----------|-----------|---------------|---------------------------------------------------------------|

94−| `id` | Number | `1` | Sequential ID for keeping track of sent messages. |

94+| `id` | Number | `1` | ID for keeping track of sent messages. |

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

121

123|----------|-----------|-----------------|-----------------------------------------------------|

124−| `id` | Number | `2` | Sequential ID for keeping track of sent messages. |

124+| `id` | Number | `2` | ID for keeping track of sent messages. |

@@ -141,15 +141,15 @@ This is for subscribing to a watch `path` of a Gall agent.

141

142**Response**

143

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

144+Eyre 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`.

145

146### Ack

147

148−This is for acknowledging a [fact](#fact) from a Gall agent to which you've subscribed.

148+This is for acknowledging an SSE event. If you `ack` one event, you also implicitly `ack` all previous events. Events must be `ack`ed.

149

151|------------|-----------|---------------|--------------------------------------------------------|

152−| `id` | Number | `3` | Sequential ID for keeping track of sent messages. |

152+| `id` | Number | `3` | ID for keeping track of sent messages. |

155

@@ -165,7 +165,7 @@ This is for acknowledging a [fact](#fact) from a Gall agent to which you've subs

165

166**Response**

167

168−Eyre will not respond to an `ack` action - acks are never acked.

168+Eyre will not respond to an `ack` action.

169

170### Unsubscribe

171

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

173

175|----------------|-----------|---------------|------------------------------------------------------------|

176−| `id` | Number | `4` | Sequential ID for keeping track of sent messages. |

176+| `id` | Number | `4` | ID for keeping track of sent messages. |

179

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

197

199|----------|-----------|---------------|---------------------------------------------------|

200−| `id` | Number | `5` | Sequential ID for keeping track of sent messages. |

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

202

203**Example**

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

257

258**Action Required**

259

260−No action is required - acks are never acked.

260+You must ack the event.

261

262### Watch Ack

263

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

301

302**Action Required**

303

304−No action is required - acks are never acked.

304+You must ack the event.

305

306−### Fact

306+### Diff

307

308−All data sent by a Gall agent on the `path` to which you've subscribed comes in as `fact`s.

308+All `fact`s sent by a Gall agent on the `path` to which you've subscribed are delivered as `diff`s. Note that Eyre makes a best effort to convert the `fact` to a `json` mark. If it can't, Eyre will crash and close the subscription, and you won't receive any `diff` for the `fact`.

309

311|------------|-----------|------------------|--------------------------------------------------------------|

@@ -325,29 +325,29 @@ All data sent by a Gall agent on the `path` to which you've subscribed comes in

325

326**Action Required**

327

328−You must [ack](#ack) each individual `fact` that comes in the event stream.

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

329

330−### Kick

330+### Quit

331

332−A `kick` comes in when a subscription has been ended. You may be intentionally `kick`ed by the Gall agent to which you're subscribed, but certain network conditions can also trigger a `kick`. As a result, it's best to try and re[subscribe](#subscribe) when you get a `kick`, and if the resulting [watch ack](#watch-ack) is negative you can then conclude the `kick` was intentional and give up.

332+A `quit` comes in when a subscription has been ended. You may be intentionally kicked by the Gall agent to which you're subscribed, but certain network conditions can also trigger a `quit`. As a result, it's best to try and re[subscribe](#subscribe) when you get a `quit`, and if the resulting [watch ack](#watch-ack) is negative you can then conclude the `quit` was intentional and give up.

333

335|------------|-----------|---------------|-----------------------------------------------|

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

338

339**Example**

340

341```json

342{

343 'id': 4,

344− 'response': 'kick'

344+ 'response': 'quit'

345}

346```

347

348**Action Required**

349

350−No action is required in response to a `kick`, but you may wish to try and re[subscribe](#subscribe).

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

351

352# Scry

353

arvo/eyre/tasks.md+36−60

@@ -24,20 +24,16 @@ This document details all the `task`s you're likely to use to interact with Eyre

25The 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.

27−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 `+clay` section of `/sys/lull.hoon` in Arvo where these `task`s, `gift`s and data structures are defined.

27+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.

28−

29−The focus of this document is on interacting with Clay from userspace applications and threads, so it doesn't delve into the internal mechanics of Clay from a kernel development perspective.

31# `%live`

29# `%live`

33−This `task` notifies Eyre of the listening HTTPS and HTTP ports. It is automatically sent to Eyre by Vere and should not be used manually.

34−

35−## Accepts

36−

37```hoon

31```hoon

38−[insecure=@ud secure=(unit @ud)]

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

39```

33```

35+This `task` notifies Eyre of the listening HTTPS and HTTP ports. It is automatically sent to Eyre by the runtime and should not be used manually.

36+

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

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

43## Returns

39## Returns

@@ -46,14 +42,12 @@ Eyre returns no `gift` in response to a `%live` `task`.

47# `%rule`

43# `%rule`

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

50−

51−## Accepts

52−

53```hoon

45```hoon

54−=http-rule

46+[%rule =http-rule]

55```

47```

49+This `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.

50+

57The [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.

51The [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.

59## Returns

53## Returns

@@ -62,14 +56,12 @@ Eyre returns no `gift` in response to a `%rule` `task`.

63# `%request`

57# `%request`

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

66−

67−## Accepts

68−

69```hoon

59```hoon

70−[secure=? =address =request:http]

60+[%request secure=? =address =request:http]

71```

61```

63+This `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.

64+

73The `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.

65The `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.

75## Returns

67## Returns

@@ -82,15 +74,13 @@ This `task` is how Eyre receives an inbound HTTP request over the local loopback

83# `%cancel-request`

75# `%cancel-request`

85−This `task` is sent to Eyre by Vere when an HTTP client closes its previously established connection. You would not normally use this manually.

86−

87−## Accepts

88−

89```hoon

77```hoon

90−~

78+[%cancel-request ~]

91```

79```

81+This `task` is sent to Eyre by the runtime when an HTTP client closes its previously established connection. You would not normally use this manually.

82+

93−Takes no arguments.

83+This `task` takes no arguments.

95## Returns

85## Returns

@@ -98,11 +88,13 @@ Eyre may `pass` a `%response` `gift` on the appropriate `duct` depending on the

99# `%connect`

89# `%connect`

100

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

91+```hoon

92+[%connect =binding app=term]

93+```

102

103−If an agent is bound in Eyre using this method, the channel system is bypassed and instead Eyre pokes HTTP requests directly into the agent as a `cage` with 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.

95+This `task` binds a Gall agent to a URL path so it can receive HTTP requests and return HTTP responses directly. 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.

104

105−Along 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` to complete the response and close the connection (though it can take more than two `fact`s).

97+Along 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).

106

107The 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.

99The 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.

108

100

@@ -110,13 +102,7 @@ The `cage` of the second and subsequent `fact`s must have a `mark` of `%http-res

110

102

111Finally, 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.

103Finally, 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.

112

104

113−## Accepts

114−

115−```hoon

116−[=binding app=term]

117−```

118−

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

105+With regard to the arguments of this `task`, [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.

120

106

121## Returns

107## Returns

122

108

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

134

120

135# `%serve`

121# `%serve`

136

122

123+```hoon

124+[%serve =binding =generator]

125+```

126+

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

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

138

128

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

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

@@ -154,12 +144,6 @@ The `?` says whether the HTTP request contained a valid session cookie and the [

154

144

155The `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.

145The `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.

156

146

157−## Accepts

158−

159−```hoon

160−[=binding =generator]

161−```

162−

163The `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 `~`.

147The `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 `~`.

164

148

165## Returns

149## Returns

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

172

156

173# `%disconnect`

157# `%disconnect`

174

158

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

176−

177−## Accepts

178−

179```hoon

159```hoon

180−=binding

160+[%disconnect =binding]

181```

161```

182

162

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

164+

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

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

184

166

185## Returns

167## Returns

@@ -188,14 +170,12 @@ Eyre returns no `gift` in response to a `%disconnect` `task`.

188

170

189# `%code-changed`

171# `%code-changed`

190

172

191−This `task` tells Eyre that the web login code has changed, causing Eyre to throw away all sessions and cookies. Typically it's automatically sent to Eyre by `hood` when you run `|code %reset`.

192−

193−## Accepts

194−

195```hoon

173```hoon

196−~

174+[%code-changed ~]

197```

175```

198

176

177+This `task` tells Eyre that the web login code has changed, causing Eyre to throw away all sessions and cookies. Typically it's automatically sent to Eyre by `hood` when you run `|code %reset`.

178+

199This `task` takes no arguments.

179This `task` takes no arguments.

200

180

201## Returns

181## Returns

@@ -204,14 +184,12 @@ Eyre returns no `gift` in response to a `%code-changed` `task`.

204

184

205# `%approve-origin`

185# `%approve-origin`

206

186

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

208−

209−## Accepts

210−

211```hoon

187```hoon

212−=origin

188+[%approve-origin =origin]

213```

189```

214

190

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

192+

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

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

216

194

217## Returns

195## Returns

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

224

202

225# `%reject-origin`

203# `%reject-origin`

226

204

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

228−

229−## Accepts

230−

231```hoon

205```hoon

232−=origin

206+[%reject-origin =origin]

233```

207```

234

208

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

210+

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

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

236

212

237## Returns

213## Returns