@@ -1,191 +0,0 @@
1−+++
2−title = "API Reference"
3−weight = 10
4−template = "doc.html"
5−+++
6−
7−In this document we describe the public interface for Iris. Namely, we describe
8−each `task` that Iris can be `%pass`ed, and which `gift`(s) Iris can `%give` in
9−return.
10−
11−## Returns to Unix
12−
13−Much of what Iris does is translating `task`s from other vanes into `card`s
14−meant for Unix via the `%request` and `%cancel-request` `task`s. What this means in practice is that Iris may be `%pass`ed a
15−`task` via some `duct`, which in response Iris then `%give`s a `gift` to Unix
16−via another `duct`. This `gift` will actually be a response to the `%born`
17−`task` that Iris was `%pass`ed when the Urbit was resumed, which came along the
18−duct to Unix.
19−
20−
21−## Tasks
22−
23−### `%born`
24−
25−Each time you start your Urbit the Arvo kernel calls the `%born` `task` for
26−Iris. This causes Iris to cancel any outstanding http requests and resets all
27−connection states.
28−
29−#### Accepts
30−
31−```hoon
32−[ ~ ]
33−```
34−
35−#### Returns
36−
37−In response to a `%born` `task` Iris `give`s a `%http-response %cancel` `gift`
38−to each outstanding connection.
39−
40−
41−### `%cancel-request`
42−
43−This `task` cancels a previous fetch. Iris knows which request is meant based on the
44−`duct` that the `task` comes on.
45−
46− We note that `%cancel-request` is also a `gift` that Iris can `%give`.
47−
48−#### Accepts
49−
50−```hoon
51−[ ~ ]
52−```
53−
54−#### Returns
55−
56−```hoon
57−[%cancel-request id=@ud]
58−```
59−Receiving this `task` causes Iris to `%give`s a `%cancel-request` `gift` to Unix,
60−which then cancels the request in the runtime. See [Returns to Unix](#returns-to-unix).
61−
62−`id` is obtained via a `(map duct @ud)`, with the `duct` corresponding to one along
63−which the `%cancel-request` `task` came with.
64−
65−
66−### `%crud`
67−
68−`%crud` is called whenever an error involving Iris occurs. It produces a crash
69−report in response.
70−
71−#### Accepts
72−
73−```hoon
74−[p=@tas q=(list tank)]
75−```
76−
77−`p` is the type of error, `q` is the error message.
78−
79−#### Returns
80−
81−Iris does not `%give` a `gift` in response to a `%crud` `task`, but it does
82−`%slip` Dill a `%flog` `task` instructing it to print the error.
83−
84−
85−### `%receive`
86−
87−The `%receive` `task` is used to receive a response from Unix to an `http-request` that
88−was made.
89−
90−#### Accepts
91−
92−```hoon
93−[id=@ud =http-event:http]
94−```
95−
96−`id` is the identification number assigned by Iris to the http connection under
97−consideration. `http-event` is a packet that contains a header and data.
98−
99−#### Returns
100−
101−The response depends on what kind of packet `http-event` is: `%start`,
102−`%continue`, or `%cancel` and whether the `complete` flag is `%.y` or `%.n`.
103−
104−If the packet says to `%start` or `%continue` and `complete=%.n`, Iris will `%give` a
105−`%http-response %progress` `gift`.
106−
107−If the packet says to `%start` or `%continue` and `complete=%.y`, Iris will
108−`%give` a `%http-response %finished` `gift`.
109−
110−If the packet says to `%cancel`, Iris will `%give` a `%http-response %cancel`
111−`gift` in return. The `complete` flag is unused here.
112−
113−
114−### `%request`
115−
116−`%request` is used to fetch a remote resource. `%request` is also a `gift` Iris
117−can `%give`.
118−
119−#### Accepts
120−
121−```hoon
122−[=request:http =outbound-config]
123−```
124−
125−A `$request` consists of the following:
126− - `=method`, the http method, which is one of `CONNECT`, `DELETE`, `GET`,
127− `HEAD`, `OPTIONS`, `POST`, `PUT`, and `TRACE`.
128− - `url=@t`, the URL being requested
129− - `=header-list`, a list of headers to pass with the request,
130− - `body=(unit octs)`, optional data to include in the request.
131−
132− A `$outbound-config` contains the number of redirects and retries that Iris
133− will attempt. By default this is 5 redirects (the recommended limit for the
134− http standard) and 3 retries.
135−
136−#### Returns
137−
138−```hoon
139−[id=@ud request=request:http]
140−```
141−Iris will `%give` a `%request` `gift` to Unix in response to a `%request`
142−`task`. See [Returns to Unix](#returns-to-unix). This `gift`
143−contains the `request` in the original `task` as well as the ID number assigned
144−by Iris for that particular http connection, which is extracted from the input `task`.
145−
146−
147−### `%trim`
148−
149−This `task` is sent by the interpreter to free up memory. It has no effect on Iris.
150−
151−#### Accepts
152−
153−```hoon
154−[ ~ ]
155−```
156−
157−#### Returns
158−
159−This `task` returns no `gift`s.
160−
161−
162−### `%vega`
163−
164−This `task` informs the vane that the kernel has been upgraded. Iris does not do
165−anything in response to this.
166−
167−#### Accepts
168−
169−```hoon
170−[ ~ ]
171−```
172−
173−#### Returns
174−
175−This `task` returns no `gift`s.
176−
177−
178−### `%wegh`
179−
180−This `task` asks Iris to product a memory usage report.
181−
182−#### Accepts
183−
184−This `task` has no arguments.
185−
186−#### Returns
187−
188−When Iris is `%pass`ed this `task`, it will `%give` a `%mass` `gift` in response
189−containing Iris' current memory usage.
190−
191−