d03e822 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

iris: fix links and headers

d03e822tinnus-napbus5 years ago

content/docs/arvo/iris/data-types.md+7−7

compare with master

unifiedsplit

@@ -4,9 +4,9 @@ weight = 2

4template = "doc.html"

5+++

7−Iris itself only has three structures defined in `lull.hoon`, but it also uses [$http](@/docs/arvo/eyre/data-types.md#http) structures which are shared between Iris and Eyre. The `$http` structures are detailed in the [Eyre](@/docs/arvo/eyre/data-types.md) Data Types documentation.

7+Iris itself only has three structures defined in `lull.hoon`, but it also uses [$http](/docs/arvo/eyre/data-types#http) structures which are shared between Iris and Eyre. The `$http` structures are detailed in the [Eyre](/docs/arvo/eyre/data-types) Data Types documentation.

9−# `$client-response`

9+## `$client-response`

11```hoon

12+$ client-response

@@ -22,15 +22,15 @@ Iris itself only has three structures defined in `lull.hoon`, but it also uses [

22 ==

23```

25−This structure represents data which Iris has fetched from a remote HTTP resource, and is what's returned in a `%http-response` `gift` (see the [%request](@/docs/arvo/iris/tasks.md#request) documentation for details) by Iris to the app or thread which requested it. There are three kinds of `client-response` - `%progress`, `%finished` and `%cancel`. A `%progress` `client-response` is a partial response, such as when an HTTP response is split into multiple separate chunks. A `%finished` `client-response` is the final complete, assembled and parsed HTTP response. A `%cancel` `client-response` is sent when the runtime cancels the request for some reason.

25+This structure represents data which Iris has fetched from a remote HTTP resource, and is what's returned in a `%http-response` `gift` (see the [%request](/docs/arvo/iris/tasks#request) documentation for details) by Iris to the app or thread which requested it. There are three kinds of `client-response` - `%progress`, `%finished` and `%cancel`. A `%progress` `client-response` is a partial response, such as when an HTTP response is split into multiple separate chunks. A `%finished` `client-response` is the final complete, assembled and parsed HTTP response. A `%cancel` `client-response` is sent when the runtime cancels the request for some reason.

27Note that at the time of writing, **neither `%progress` nor `%cancel` `client-response`s are implemented**, so in practice you'll only ever get a single `%finished` `client-response`.

29−In a `%progress` `client-response`, the [$response-header:http](@/docs/arvo/eyre/data-types.md#response-header-http) contains the HTTP status code and headers. The `bytes-read` field is the total number of bytes fetched so far. The `expected-size` field is the total size specified in the content-length header if it has one. The `incremental` field is the data received since the last `%http-response`.

29+In a `%progress` `client-response`, the [$response-header:http](/docs/arvo/eyre/data-types#response-headerhttp) contains the HTTP status code and headers. The `bytes-read` field is the total number of bytes fetched so far. The `expected-size` field is the total size specified in the content-length header if it has one. The `incremental` field is the data received since the last `%http-response`.

31In a `%finished` `client-response`, the `full-file` is the complete body of the HTTP message as a (maybe) [$mime-data](#mime-data).

33−# `$mime-data`

33+## `$mime-data`

35```hoon

36+$ mime-data

@@ -39,7 +39,7 @@ In a `%finished` `client-response`, the `full-file` is the complete body of the

40Unvalidated mime data that has been fetched from a remote HTTP resource.

42−# `$outbound-config`

42+## `$outbound-config`

44```hoon

45+$ outbound-config

@@ -49,6 +49,6 @@ Unvalidated mime data that has been fetched from a remote HTTP resource.

49 ==

50```

52−This structure is used in a [%request task](@/docs/arvo/iris/tasks.md#request) to specify settings for an HTTP request. The `redirects` field specifies the number of redirects to automatically follow before failing, and defaults to 5. The `retries` field specifies the number of times to retry a failed request before giving up, and defaults to 3.

52+This structure is used in a [%request task](/docs/arvo/iris/tasks#request) to specify settings for an HTTP request. The `redirects` field specifies the number of redirects to automatically follow before failing, and defaults to 5. The `retries` field specifies the number of times to retry a failed request before giving up, and defaults to 3.

54Note that at the time of writing, **neither redirects nor retries have been implemented**, so these settings will not do anything and you can just use the bunt value in all cases.

content/docs/arvo/iris/example.md+1−2

@@ -30,7 +30,7 @@ Here we'll look at a simple example of fetching a remote HTTP resource with Iris

30(pure:m !>(`@t`q.data.u.full-file.client-response.q.res))

31```

33−This thread takes a fully qualified URL in a `@t` as an argument. It will ask Iris to fetch the HTTP resource at the given URL by passing it a [%request task](@/docs/arvo/iris/tasks.md#request) containing an HTTP GET [$request:http](@/docs/arvo/eyre/data-types.md#request-http):

33+This thread takes a fully qualified URL in a `@t` as an argument. It will ask Iris to fetch the HTTP resource at the given URL by passing it a [%request task](/docs/arvo/iris/tasks#request) containing an HTTP GET [$request:http](/docs/arvo/eyre/data-types#requesthttp):

35```hoon

36=/ url=@t (need !<((unit @t) arg))

@@ -58,7 +58,6 @@ Let's try it out:

58 [key='cache-control' value='max-age=604800']

59 [key='content-type' value='text/html; charset=UTF-8']

60 [key='date' value='Thu, 24 Jun 2021 04:12:13 GMT']

61− [key='etag' value='"3147526947+ident"']

62 [key='expires' value='Thu, 01 Jul 2021 04:12:13 GMT']

61 [key='expires' value='Thu, 01 Jul 2021 04:12:13 GMT']

63 [key='last-modified' value='Thu, 17 Oct 2019 07:18:26 GMT']

62 [key='last-modified' value='Thu, 17 Oct 2019 07:18:26 GMT']

64 [key='server' value='ECS (oxr/8328)']

63 [key='server' value='ECS (oxr/8328)']

content/docs/arvo/iris/iris.md+4−4

@@ -8,10 +8,10 @@ Iris is the HTTP client vane.

9Gall agents and Spider threads pass Iris HTTP requests, Iris makes the request to the specified URL, and finally returns the HTTP response back to the app or thread that requested it.

11−# Iris Documentation Sections

11+## Sections

13−- [Data Types](@/docs/arvo/iris/data-types.md) - Reference documentation of the data types used by Iris.

13+[Data Types](/docs/arvo/iris/data-types) - Reference documentation of the data types used by Iris.

15−- [API Reference](@/docs/arvo/eyre/tasks.md) - The `task`s Iris takes and the `gift`s it returns.

15+[API Reference](/docs/arvo/eyre/tasks) - The `task`s Iris takes and the `gift`s it returns.

17−- [Example](@/docs/arvo/iris/example.md) - An example of using Iris to fetch a remote HTTP resource.

17+[Example](/docs/arvo/iris/example) - An example of using Iris to fetch a remote HTTP resource.

content/docs/arvo/iris/tasks.md+12−14

@@ -4,9 +4,9 @@ weight = 3

4template = "doc.html"

5+++

7−This document details the `task`s that can be sent to Iris. Iris only has a couple of `task`s you can use - [%request](#request) and [%cancel-request](#cancel-request).

7+This document details the `task`s that can be sent to Iris. Iris only has a couple of `task`s you can use: [%request](#request) and [%cancel-request](#cancel-request).

9−# `%request`

9+## `%request`

11```hoon

12[%request =request:http =outbound-config]

@@ -14,11 +14,11 @@ This document details the `task`s that can be sent to Iris. Iris only has a coup

15Fetch a remote HTTP resource.

17−The [$request:http](@/docs/arvo/eyre/data-types.md#request-http) is the request itself and contains the HTTP method, the fully qualified target URL, a list of HTTP headers to be included and maybe the data for the body of the request.

17+The [$request:http](/docs/arvo/eyre/data-types#requesthttp) is the request itself and contains the HTTP method, the fully qualified target URL, a list of HTTP headers to be included and maybe the data for the body of the request.

19−The [$outbound-config](@/docs/arvo/iris/data-types.md#outbound-config) specifies the number of redirects to follow before failing and the number of retries to attempt before giving up. The default values are `5` and `3` respectively. As of writing, **retries and auto-following redirects are not implemented**, so what you specify here is irrelevant and you can just use the bunt value of `outbound-config`.

19+The [$outbound-config](/docs/arvo/iris/data-types#outbound-config) specifies the number of redirects to follow before failing and the number of retries to attempt before giving up. The default values are `5` and `3` respectively. As of writing, **retries and auto-following redirects are not implemented**, so what you specify here is irrelevant and you can just use the bunt value of `outbound-config`.

21−## Returns

21+### Returns

23Iris returns a `%http-response` `gift` in response to a `%request` task. A `%response` `gift` looks like:

@@ -26,17 +26,17 @@ Iris returns a `%http-response` `gift` in response to a `%request` task. A `%res

26[%http-response =client-response]

27```

29−The [$client-response](@/docs/arvo/iris/data-types.md#client-response) contains the HTTP response from the server including the status code, HTTP headers and any data along with its mime type.

29+The [$client-response](/docs/arvo/iris/data-types#client-response) contains the HTTP response from the server including the status code, HTTP headers and any data along with its mime type.

31The `client-response` structure specifies three kinds of responses - `%progress`, `%finished` and `%cancel`. The `%progress` response would contain each chunk of the message as it came in, `%finished` would contain the final assembled message from Vere's buffer, and `%cancel` would be sent if the runtime cancels the request.

33Note that neither `%progress` partial messages nor `%cancel` responses have been implemented in Vere at the time of writing, so **you will only ever receive a single `%http-response` `gift` with a `%finished` `client-response`**. If the request fails for some reason, you'll still get an empty `%finished` `client-response` with a `504` status code.

35−## Example

35+### Example

37−See the [Example](@/docs/arvo/iris/example.md) document.

37+See the [Example](/docs/arvo/iris/example) document.

39−# `%cancel-request`

39+## `%cancel-request`

41```hoon

42[%cancel-request ~]

@@ -46,11 +46,11 @@ Cancel a previous request to fetch a remote HTTP resource.

47A `%cancel-request` `task` does not take any arguments, the [request](#request) to cancel is determined implicitly.

49−## Returns

49+### Returns

51Iris does not return any `gift` in response to a `%cancel-request` `task`. You will also not receive any `gift` back from the original `%request` `task` you've cancelled.

53−# `%receive`

53+## `%receive`

55```hoon

56[%receive id=@ud =http-event:http]

@@ -58,6 +58,4 @@ Iris does not return any `gift` in response to a `%cancel-request` `task`. You w

59Receives HTTP data from outside. This `task` is sent to Iris by the runtime, you would not used it manually.

61−## Accepts

62−

63−The `id` is a sequential ID for the event and the [$http-event:http](@/docs/arvo/eyre/data-types.md#http-event-http) contains the HTTP headers and data.

61+The `id` is a sequential ID for the event and the [$http-event:http](/docs/arvo/eyre/data-types#http-eventhttp) contains the HTTP headers and data.