git.iko.soy/urbit.org
on master help sign in
Merge pull request #837 from urbit/iris-public-api
1e848b8poprox
reference/vane-apis/iris.mdnew file+193
compare with master
unifiedsplit
@@ -0,0 +1,193 @@
1++++
2+title = "Iris Public API"
3+weight = 5
4+template = "doc.html"
5++++
6+
7+# Iris
8+
9+In 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
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.
21+
22+
23+## Tasks
24+
25+### `%born`
26+
27+Each time you start your Urbit the Arvo kernel calls the `%born` `task` for
28+Iris. This causes Iris to cancel any outstanding http requests and resets all
29+connection states.
30+
31+#### Accepts
32+
33+```hoon
34+[ ~ ]
35+```
36+
37+#### Returns
38+
39+In response to a `%born` `task` Iris `give`s a `%http-response %cancel` `gift`
40+to each outstanding connection.
41+
42+
43+### `%cancel-request`
44+
45+This `task` cancels a previous fetch. Iris knows which request is meant based on the
46+`duct` that the `task` comes on.
47+
48+ We note that `%cancel-request` is also a `gift` that Iris can `%give`.
49+
50+#### Accepts
51+
52+```hoon
53+[ ~ ]
54+```
55+
56+#### Returns
57+
58+```hoon
59+[%cancel-request id=@ud]
60+```
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
65+which the `%cancel-request` `task` came with.
66+
67+
68+### `%crud`
69+
70+`%crud` is called whenever an error involving Iris occurs. It produces a crash
71+report in response.
72+
73+#### Accepts
74+
75+```hoon
76+[p=@tas q=(list tank)]
77+```
78+
79+`p` is the type of error, `q` is the error message.
80+
81+#### Returns
82+
83+Iris 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.
85+
86+
87+### `%receive`
88+
89+The `%receive` `task` is used to receive a response from Unix to an `http-request` that
90+was made.
91+
92+#### Accepts
93+
94+```hoon
95+[id=@ud =http-event:http]
96+```
97+
98+`id` is the identification number assigned by Iris to the http connection under
99+consideration. `http-event` is a packet that contains a header and data.
100+
101+#### Returns
102+
103+The response depends on what kind of packet `http-event` is: `%start`,
104+`%continue`, or `%cancel` and whether the `complete` flag is `%.y` or `%.n`.
105+
106+If the packet says to `%start` or `%continue` and `complete=%.n`, Iris will `%give` a
107+`%http-response %progress` `gift`.
108+
109+If the packet says to `%start` or `%continue` and `complete=%.y`, Iris will
110+`%give` a `%http-response %finished` `gift`.
111+
112+If the packet says to `%cancel`, Iris will `%give` a `%http-response %cancel`
113+`gift` in return. The `complete` flag is unused here.
114+
115+
116+### `%request`
117+
118+`%request` is used to fetch a remote resource. `%request` is also a `gift` Iris
119+can `%give`.
120+
121+#### Accepts
122+
123+```hoon
124+[=request:http =outbound-config]
125+```
126+
127+A `$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.
133+
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.
137+
138+#### Returns
139+
140+```hoon
141+[id=@ud request=request:http]
142+```
143+Iris will `%give` a `%request` `gift` to Unix in response to a `%request`
144+`task`. See [Returns to Unix](#returns-to-unix). This `gift`
145+contains the `request` in the original `task` as well as the ID number assigned
146+by Iris for that particular http connection, which is extracted from the input `task`.
147+
148+
149+### `%trim`
150+
151+This `task` is sent by the interpreter to free up memory. It has no effect on Iris.
152+
153+#### Accepts
154+
155+```hoon
156+[ ~ ]
157+```
158+
159+#### Returns
160+
161+This `task` returns no `gift`s.
162+
163+
164+### `%vega`
165+
166+This `task` informs the vane that the kernel has been upgraded. Iris does not do
167+anything in response to this.
168+
169+#### Accepts
170+
171+```hoon
172+[ ~ ]
173+```
174+
175+#### Returns
176+
177+This `task` returns no `gift`s.
178+
179+
180+### `%wegh`
181+
182+This `task` asks Iris to product a memory usage report.
183+
184+#### Accepts
185+
186+This `task` has no arguments.
187+
188+#### Returns
189+
190+When Iris is `%pass`ed this `task`, it will `%give` a `%mass` `gift` in response
191+containing Iris' current memory usage.
192+
193+