In this document we describe the public interface for Iris. Namely, we describe each task that Iris can be %passed, and which gift(s) Iris can %give in return.

Returns to Unix

Much of what Iris does is translating tasks from other vanes into cards meant for Unix via the %request and %cancel-request tasks. What this means in practice is that Iris may be %passed a task via some duct, which in response Iris then %gives a gift to Unix via another duct. This gift will actually be a response to the %born task that Iris was %passed when the Urbit was resumed, which came along the duct to Unix.

Tasks

%born

Each time you start your Urbit the Arvo kernel calls the %born task for Iris. This causes Iris to cancel any outstanding http requests and resets all connection states.

Accepts

[ ~ ]

Returns

In response to a %born task Iris gives a %http-response %cancel gift to each outstanding connection.

%cancel-request

This task cancels a previous fetch. Iris knows which request is meant based on the duct that the task comes on.

We note that %cancel-request is also a gift that Iris can %give.

Accepts

[ ~ ]

Returns

[%cancel-request id=@ud]

Receiving this task causes Iris to %gives a %cancel-request gift to Unix, which then cancels the request in the runtime. See Returns to Unix.

id is obtained via a (map duct @ud), with the duct corresponding to one along which the %cancel-request task came with.

%crud

%crud is called whenever an error involving Iris occurs. It produces a crash report in response.

Accepts

[p=@tas q=(list tank)]

p is the type of error, q is the error message.

Returns

Iris does not %give a gift in response to a %crud task, but it does %slip Dill a %flog task instructing it to print the error.

%receive

The %receive task is used to receive a response from Unix to an http-request that was made.

Accepts

[id=@ud =http-event:http]

id is the identification number assigned by Iris to the http connection under consideration. http-event is a packet that contains a header and data.

Returns

The response depends on what kind of packet http-event is: %start, %continue, or %cancel and whether the complete flag is %.y or %.n.

If the packet says to %start or %continue and complete=%.n, Iris will %give a %http-response %progress gift.

If the packet says to %start or %continue and complete=%.y, Iris will %give a %http-response %finished gift.

If the packet says to %cancel, Iris will %give a %http-response %cancel gift in return. The complete flag is unused here.

%request

%request is used to fetch a remote resource. %request is also a gift Iris can %give.

Accepts

[=request:http =outbound-config]

A $request consists of the following:

• =method, the http method, which is one of CONNECT, DELETE, GET,

HEAD, OPTIONS, POST, PUT, and TRACE.

• url=@t, the URL being requested
• =header-list, a list of headers to pass with the request,
• body=(unit octs), optional data to include in the request.

A $outbound-config contains the number of redirects and retries that Iris will attempt. By default this is 5 redirects (the recommended limit for the http standard) and 3 retries.

Returns

[id=@ud request=request:http]

Iris will %give a %request gift to Unix in response to a %request task. See Returns to Unix. This gift contains the request in the original task as well as the ID number assigned by Iris for that particular http connection, which is extracted from the input task.

%trim

This task is sent by the interpreter to free up memory. It has no effect on Iris.

Accepts

[ ~ ]

Returns

This task returns no gifts.

%vega

This task informs the vane that the kernel has been upgraded. Iris does not do anything in response to this.

Accepts

[ ~ ]

Returns

This task returns no gifts.

%wegh

This task asks Iris to product a memory usage report.

Accepts

This task has no arguments.

Returns

When Iris is %passed this task, it will %give a %mass gift in response containing Iris' current memory usage.