d03e822 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

iris: fix links and headers

commitd03e82260d40177e22f2353a4fa9c0614d4bc2af authortinnus-napbus <admin@tinnus-napbus.xyz> dateThu 29 Jul 2021, 01:26 (5 years ago) parent0671f0f

4 files changed+24−27

compare with master

unifiedsplit

content/docs/arvo/iris/data-types.md+7−7 content/docs/arvo/iris/example.md+1−2 content/docs/arvo/iris/iris.md+4−4 content/docs/arvo/iris/tasks.md+12−14

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

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

44template = "doc.html"

55+++

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`

1010

1111```hoon

1212+$ client-response

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

2222 ==

2323```

2424

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.

2626

2727Note 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`.

2828

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`.

3030

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

3232

33−# `$mime-data`

33+## `$mime-data`

3434

3535```hoon

3636+$ mime-data

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

3939

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

4141

42−# `$outbound-config`

42+## `$outbound-config`

4343

4444```hoon

4545+$ outbound-config

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

4949 ==

5050```

5151

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.

5353

5454Note 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

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

3131```

3232

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):

3434

3535```hoon

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

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

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

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

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

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

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

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

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

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

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

99Gall 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.

1010

11−# Iris Documentation Sections

11+## Sections

1212

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.

1414

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.

1616

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

44template = "doc.html"

55+++

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`

1010

1111```hoon

1212[%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

1414

1515Fetch a remote HTTP resource.

1616

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.

1818

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`.

2020

21−## Returns

21+### Returns

2222

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

2424

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

2626[%http-response =client-response]

2727```

2828

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.

3030

3131The `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.

3232

3333Note 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.

3434

35−## Example

35+### Example

3636

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

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

3838

39−# `%cancel-request`

39+## `%cancel-request`

4040

4141```hoon

4242[%cancel-request ~]

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

4646

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

4848

49−## Returns

49+### Returns

5050

5151Iris 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.

5252

53−# `%receive`

53+## `%receive`

5454

5555```hoon

5656[%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

5858

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

6060

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.