@@ -7,7 +7,18 @@ template = "doc.html"
9In this document we describe the public interface for Iris. Namely, we describe
9In 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
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.
@@ -47,8 +58,10 @@ This `task` cancels a previous fetch. Iris knows which request is meant based on
48[%cancel-request id=@ud]
59[%cancel-request id=@ud]
50−Iris `%give`s a `%cancel-request` `gift` in response to this `task`. `id` is
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).
51−obtained via a `(map duct @ud)`, with the `duct` corresponding to one along
64+`id` is obtained via a `(map duct @ud)`, with the `duct` corresponding to one along
52which the `%cancel-request` `task` came with.
65which the `%cancel-request` `task` came with.
@@ -73,7 +86,7 @@ Iris does not `%give` a `gift` in response to a `%crud` `task`, but it does
74### `%receive`
87### `%receive`
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
79#### Accepts
92#### Accepts
@@ -127,7 +140,8 @@ A `$request` consists of the following:
128[id=@ud request=request:http]
141[id=@ud request=request:http]
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`
131contains the `request` in the original `task` as well as the ID number assigned
145contains the `request` in the original `task` as well as the ID number assigned
132by Iris for that particular http connection, which is extracted from the input `task`.
146by Iris for that particular http connection, which is extracted from the input `task`.