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