git.iko.soy/urbit.org
on 705ca06 help sign in
urbit.org/reference/vane-apis/iris.md
193 lines 4.6 kB history raw
1+++
2title = "Iris Public API"
3weight = 5
4template = "doc.html"
5+++
7# Iris
9In this document we describe the public interface for Iris. Namely, we describe
10each `task` that Iris can be `%pass`ed, and which `gift`(s) Iris can `%give` in
11return.
13## Returns to Unix
15Much of what Iris does is translating `task`s from other vanes into `card`s
16meant 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
18via 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
20duct to Unix.
23## Tasks
25### `%born`
27Each time you start your Urbit the Arvo kernel calls the `%born` `task` for
28Iris. This causes Iris to cancel any outstanding http requests and resets all
29connection states.
31#### Accepts
33```hoon
34[ ~ ]
35```
37#### Returns
39In response to a `%born` `task` Iris `give`s a `%http-response %cancel` `gift`
40to each outstanding connection.
43### `%cancel-request`
45This `task` cancels a previous fetch. Iris knows which request is meant based on the
46`duct` that the `task` comes on.
48 We note that `%cancel-request` is also a `gift` that Iris can `%give`.
50#### Accepts
52```hoon
53[ ~ ]
54```
56#### Returns
58```hoon
59[%cancel-request id=@ud]
60```
61Receiving this `task` causes Iris to `%give`s a `%cancel-request` `gift` to Unix,
62which then cancels the request in the runtime. See [Returns to Unix](#returns-to-unix).
64`id` is obtained via a `(map duct @ud)`, with the `duct` corresponding to one along
65which the `%cancel-request` `task` came with.
68### `%crud`
70`%crud` is called whenever an error involving Iris occurs. It produces a crash
71report in response.
73#### Accepts
75```hoon
76[p=@tas q=(list tank)]
77```
79`p` is the type of error, `q` is the error message.
81#### Returns
83Iris does not `%give` a `gift` in response to a `%crud` `task`, but it does
84`%slip` Dill a `%flog` `task` instructing it to print the error.
87### `%receive`
89The `%receive` `task` is used to receive a response from Unix to an `http-request` that
90was made.
92#### Accepts
94```hoon
95[id=@ud =http-event:http]
96```
98`id` is the identification number assigned by Iris to the http connection under
99consideration. `http-event` is a packet that contains a header and data.
101#### Returns
103The response depends on what kind of packet `http-event` is: `%start`,
104`%continue`, or `%cancel` and whether the `complete` flag is `%.y` or `%.n`.
106If the packet says to `%start` or `%continue` and `complete=%.n`, Iris will `%give` a
107`%http-response %progress` `gift`.
109If the packet says to `%start` or `%continue` and `complete=%.y`, Iris will
110`%give` a `%http-response %finished` `gift`.
112If the packet says to `%cancel`, Iris will `%give` a `%http-response %cancel`
113`gift` in return. The `complete` flag is unused here.
116### `%request`
118`%request` is used to fetch a remote resource. `%request` is also a `gift` Iris
119can `%give`.
121#### Accepts
123```hoon
124[=request:http =outbound-config]
125```
127A `$request` consists of the following:
128 - `=method`, the http method, which is one of `CONNECT`, `DELETE`, `GET`,
129 `HEAD`, `OPTIONS`, `POST`, `PUT`, and `TRACE`.
130 - `url=@t`, the URL being requested
131 - `=header-list`, a list of headers to pass with the request,
132 - `body=(unit octs)`, optional data to include in the request.
134 A `$outbound-config` contains the number of redirects and retries that Iris
135 will attempt. By default this is 5 redirects (the recommended limit for the
136 http standard) and 3 retries.
138#### Returns
140```hoon
141[id=@ud request=request:http]
142```
143Iris will `%give` a `%request` `gift` to Unix in response to a `%request`
144`task`. See [Returns to Unix](#returns-to-unix). This `gift`
145contains the `request` in the original `task` as well as the ID number assigned
146by Iris for that particular http connection, which is extracted from the input `task`.
149### `%trim`
151This `task` is sent by the interpreter to free up memory. It has no effect on Iris.
153#### Accepts
155```hoon
156[ ~ ]
157```
159#### Returns
161This `task` returns no `gift`s.
164### `%vega`
166This `task` informs the vane that the kernel has been upgraded. Iris does not do
167anything in response to this.
169#### Accepts
171```hoon
172[ ~ ]
173```
175#### Returns
177This `task` returns no `gift`s.
180### `%wegh`
182This `task` asks Iris to product a memory usage report.
184#### Accepts
186This `task` has no arguments.
188#### Returns
190When Iris is `%pass`ed this `task`, it will `%give` a `%mass` `gift` in response
191containing Iris' current memory usage.