@@ -24,20 +24,16 @@ This document details all the `task`s you're likely to use to interact with Eyre
2424
2525The 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.
2626
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.
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.
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.
3028
3129# `%live`
3230
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−
3731```hoon
38−[insecure=@ud secure=(unit @ud)]
32+[%live insecure=@ud secure=(unit @ud)]
3933```
4034
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+
4137The `insecure` field is the HTTP port and `secure` is the optional HTTPS port.
4238
4339## Returns
@@ -46,14 +42,12 @@ Eyre returns no `gift` in response to a `%live` `task`.
4642
4743# `%rule`
4844
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−
5345```hoon
54−=http-rule
46+[%rule =http-rule]
5547```
5648
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+
5751The [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.
5852
5953## Returns
@@ -62,14 +56,12 @@ Eyre returns no `gift` in response to a `%rule` `task`.
6256
6357# `%request`
6458
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−
6959```hoon
70−[secure=? =address =request:http]
60+[%request secure=? =address =request:http]
7161```
7262
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+
7365The `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.
7466
7567## Returns
@@ -82,15 +74,13 @@ This `task` is how Eyre receives an inbound HTTP request over the local loopback
8274
8375# `%cancel-request`
8476
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−
8977```hoon
90−~
78+[%cancel-request ~]
9179```
9280
93−Takes no arguments.
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+
83+This `task` takes no arguments.
9484
9585## Returns
9686
@@ -98,11 +88,13 @@ Eyre may `pass` a `%response` `gift` on the appropriate `duct` depending on the
9888
9989# `%connect`
10090
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+```
10294
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.
10496
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).
10698
10799The 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.
108100
@@ -110,13 +102,7 @@ The `cage` of the second and subsequent `fact`s must have a `mark` of `%http-res
110102
111103Finally, 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.
112104
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.
120106
121107## Returns
122108
@@ -134,6 +120,10 @@ See the [Direct HTTP Handling With Gall Agents](@/docs/arvo/eyre/examples.md#dir
134120
135121# `%serve`
136122
123+```hoon
124+[%serve =binding =generator]
125+```
126+
137127This `task` binds a generator to a URL path so it can receive HTTP requests and return HTTP responses.
138128
139129The 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 [
154144
155145The `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.
156146
157−## Accepts
158−
159−```hoon
160−[=binding =generator]
161−```
162−
163147The `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 `~`.
164148
165149## Returns
@@ -172,14 +156,12 @@ See the [Generators](@/docs/arvo/eyre/examples.md#generators) section of the [Ex
172156
173157# `%disconnect`
174158
175−This `task` deletes a URL binding previously set by a `%connect` or `%serve` `task`.
176−
177−## Accepts
178−
179159```hoon
180−=binding
160+[%disconnect =binding]
181161```
182162
163+This `task` deletes a URL binding previously set by a `%connect` or `%serve` `task`.
164+
183165The [binding](@/docs/arvo/eyre/data-types.md#binding) is the URL path and domain of the binding you want to delete.
184166
185167## Returns
@@ -188,14 +170,12 @@ Eyre returns no `gift` in response to a `%disconnect` `task`.
188170
189171# `%code-changed`
190172
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−
195173```hoon
196−~
174+[%code-changed ~]
197175```
198176
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+
199179This `task` takes no arguments.
200180
201181## Returns
@@ -204,14 +184,12 @@ Eyre returns no `gift` in response to a `%code-changed` `task`.
204184
205185# `%approve-origin`
206186
207−This `task` tells Eyre to start responding positively to CORS requests for the specified `origin`.
208−
209−## Accepts
210−
211187```hoon
212−=origin
188+[%approve-origin =origin]
213189```
214190
191+This `task` tells Eyre to start responding positively to CORS requests for the specified `origin`.
192+
215193The [origin](@/docs/arvo/eyre/data-types.md#origin) is a CORS origin like `http://foo.example` you want to approve.
216194
217195## Returns
@@ -224,14 +202,12 @@ See the [Managing CORS Origins](@/docs/arvo/eyre/examples.md#managing-cors-origi
224202
225203# `%reject-origin`
226204
227−This `task` tells Eyre to start responding negatively to CORS requests for the specified `origin`.
228−
229−## Accepts
230−
231205```hoon
232−=origin
206+[%reject-origin =origin]
233207```
234208
209+This `task` tells Eyre to start responding negatively to CORS requests for the specified `origin`.
210+
235211The [origin](@/docs/arvo/eyre/data-types.md#origin) is a CORS origin like `http://foo.example` you want want to reject.
236212
237213## Returns