@@ -7,7 +7,18 @@ template = "doc.html"
77# Iris
88
99In this document we describe the public interface for Iris. Namely, we describe
10−each `task` that Iris can be `%pass`ed, and which `gift`(s) Iris can `%give` in return.
10+each `task` that Iris can be `%pass`ed, and which `gift`(s) Iris can `%give` in
11+return.
12+
13+## Returns to Unix
14+
15+Much of what Iris does is translating `task`s from other vanes into `card`s
16+meant for Unix via the `%request` and `%cancel-request` `task`s. What this means in practice is that Iris may be `%pass`ed a
17+`task` via some `duct`, which in response Iris then `%give`s a `gift` to Unix
18+via another `duct`. This `gift` will actually be a response to the `%born`
19+`task` that Iris was `%pass`ed when the Urbit was resumed, which came along the
20+duct to Unix. This is not an ideal situation but also one not easily remedied.
21+
1122
1223## Tasks
1324
@@ -47,8 +58,10 @@ This `task` cancels a previous fetch. Iris knows which request is meant based on
4758```hoon
4859[%cancel-request id=@ud]
4960```
50−Iris `%give`s a `%cancel-request` `gift` in response to this `task`. `id` is
51−obtained via a `(map duct @ud)`, with the `duct` corresponding to one along
61+Receiving this `task` causes Iris to `%give`s a `%cancel-request` `gift` to Unix,
62+which then cancels the request in the runtime. See [Returns to Unix](#returns-to-unix).
63+
64+`id` is obtained via a `(map duct @ud)`, with the `duct` corresponding to one along
5265which the `%cancel-request` `task` came with.
5366
5467
@@ -73,7 +86,7 @@ Iris does not `%give` a `gift` in response to a `%crud` `task`, but it does
7386
7487### `%receive`
7588
76−The `%receive` `task` is used to receive a response to an `http-request` that
89+The `%receive` `task` is used to receive a response from Unix to an `http-request` that
7790was made.
7891
7992#### Accepts
@@ -127,7 +140,8 @@ A `$request` consists of the following:
127140```hoon
128141[id=@ud request=request:http]
129142```
130−Iris will `%give` a `%request` `gift` in response to a `%request` `task`. This
143+Iris will `%give` a `%request` `gift` to Unix in response to a `%request`
144+`task`. See [Returns from Unix](#returns-from-unix). This `gift`
131145contains the `request` in the original `task` as well as the ID number assigned
132146by Iris for that particular http connection, which is extracted from the input `task`.
133147