urbit/developers.urbit.org
1
1
Fork 0
mirror of https://github.com/urbit/developers.urbit.org.git synced 2024-09-11 13:55:59 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #363 from urbit/add-eyre-cache-tasks

Browse Source 
add %set-response task and cache-entry type to eyre ref for 413
This commit is contained in:
tinnus-napbus 2023-05-10 11:09:44 +12:00 committed by GitHub
commit 5b958dc41a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 122 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
content/reference/arvo/eyre/data-types.md
View File

@ -11,6 +11,24 @@ This document describes the data types used by Eyre as defined in `/sys/lull.hoo
## Eyre
### `$cache-entry`
```hoon
+$ cache-entry
$: auth=?
$= body
$% [%payload =simple-payload:http]
== ==
```
- `auth`: Whether the request must include a valid session cookie or otherwise
be authenticated. If this is false, the entry will be publicly accessible.
- `body`: The HTTP response to give. This contains a `[%payload
=simple-payload:http]`. See the [`$simple-payload:http`](#simple-payloadhttp)
for more details of the data.
---
### `$origin`
```hoon
@ -19,6 +37,8 @@ This document describes the data types used by Eyre as defined in `/sys/lull.hoo
A single CORS origin as used in an HTTP Origin header and the [$cors-registry](#cors-registry).
---
### `$cors-registry`
```hoon
@ -31,6 +51,8 @@ A single CORS origin as used in an HTTP Origin header and the [$cors-registry](#
CORS origins categorised by approval status. The `requests` `set` contains all [$origin](#origin)s Eyre has received in the headers of HTTP requests that have not been explicitly approved or rejected. The `approved` and `rejected` `set`s are those that have been explicitly approved or rejected.
---
### `$outstanding-connection`
```hoon
@ -44,6 +66,8 @@ CORS origins categorised by approval status. The `requests` `set` contains all [
An HTTP connection that is currently open. The [$action](#action) is how it's being handled (e.g. by a Gall app, the channel system, etc). The [$inbound-request](#inbound-request) is the original request which opened the connection. The `response-header` contains the status code and headers. The `bytes-sent` is the total bytes sent so far in response.
---
### `$authentication-state`
```hoon
@ -52,6 +76,8 @@ An HTTP connection that is currently open. The [$action](#action) is how it's be
This represents the authentication state of all sessions. It maps session cookies (without the `urbauth-{SHIP}=` prefix) to [$session](#session)s.
---
### `$session`
```hoon
@ -63,6 +89,8 @@ This represents the authentication state of all sessions. It maps session cookie
This represents server-side data about a session. The `expiry-time` is when the `session` expires and `channels` is the `set` of [$channel](#channel) names opened by the session.
---
### `$channel-state`
```hoon
@ -74,6 +102,8 @@ This represents server-side data about a session. The `expiry-time` is when the
The state used by the channel system. The `session` is a `map` between channel names and [$channel](#channel)s and the `duct-to-key` `map`s `duct`s to `channel` names.
---
### `$timer`
```hoon
@ -85,6 +115,8 @@ The state used by the channel system. The `session` is a `map` between channel n
A reference to a timer so it can be cancelled or updated. The `date` is when it will fire and the `duct` is what set the timer.
---
### `$channel-event`
```hoon
@ -98,6 +130,8 @@ A reference to a timer so it can be cancelled or updated. The `date` is when it
An unacknowledged event in the channel system.
---
### `$channel`
```hoon
@ -114,6 +148,8 @@ An unacknowledged event in the channel system.
This is the state of a particular channel in the channel system. The `state` is either the expiration time or the duct currently listening. The `next-id` is the next event ID to be used in the event stream. The `last-ack` is the date of the last client ack and is used for clog calculations in combination with `unacked`. The `events` queue contains all unacked events - `id` is the server-set event ID, `request-id` is the client-set request ID and the [$channel-event](#channel-event) is the event itself. The `unacked` `map` contains the unacked event count per `request-id` and is used for clog calculations. The `subscriptions` `map` contains gall subscriptions by `request-id`. The `heartbeat` is the SSE heartbeat [$timer](#timer).
---
### `$binding`
```hoon
@ -125,6 +161,8 @@ This is the state of a particular channel in the channel system. The `state` is
A `binding` is a rule to match a URL `path` and optional `site` domain which can then be tied to an [$action](#action). A `path` of `/foo` will also match `/foo/bar`, `/foo/bar/baz`, etc. If the `site` is `~` it will be determined implicitly. A binding must be unique.
---
### `$action`
```hoon
@ -141,6 +179,8 @@ A `binding` is a rule to match a URL `path` and optional `site` domain which can
The action to take when a [$binding](#binding) matches an incoming HTTP request.
---
### `$generator`
```hoon
@ -153,6 +193,8 @@ The action to take when a [$binding](#binding) matches an incoming HTTP request.
This refers to a generator on a local ship that can handle requests. Note that serving generators via Eyre is not fully implmented and should not be used.
---
### `$http-config`
```hoon
@ -166,6 +208,8 @@ This refers to a generator on a local ship that can handle requests. Note that s
The configuration of the runtime HTTP server itself. The `secure` field contains the PEM-encoded RSA private key and certificate or certificate chain when using HTTPS, and otherwise is `~` when using plain HTTP. The `proxy` field is not currently used. The `log` field turns on HTTP(S) access logs but is not currently implemented. The `redirect` field turns on 301 redirects to upgrade HTTP to HTTPS if the `key` and `cert` are set in `secure`.
---
### `$http-rule`
```hoon
@ -177,6 +221,8 @@ The configuration of the runtime HTTP server itself. The `secure` field contains
This is for updating the server configuration. In the case of `%cert`, a `cert` of `~` clears the HTTPS cert & key, otherwise `cert` contains the PEM-encoded RSA private key and certificate or certificate chain. In the case of `%turf`, a `%put` `action` sets a domain name and a `%del` `action` removes it. The [$turf](#turf) contains the domain name.
---
### `$address`
```hoon
@ -188,6 +234,8 @@ This is for updating the server configuration. In the case of `%cert`, a `cert`
A client IP address.
---
### `$inbound-request`
```hoon
@ -201,6 +249,8 @@ A client IP address.
An inbound HTTP request and metadata. The `authenticated` field says whether the request was made with a valid session cookie. The `secure` field says whether it was made with HTTPS. The [$address](#address) is the IP address from which the request originated, except if it came from localhost and included a `Forwarded` header, in which case it's the address specified in that header. The [$request:http](#requesthttp) contains the HTTP request itself.
---
## HTTP
### `$header-list:http`
@ -211,6 +261,8 @@ An inbound HTTP request and metadata. The `authenticated` field says whether the
An ordered list of HTTP headers. The `key` is the header name e.g `'Content-Type'` and the `value` is the value e.g. `text/html`.
---
### `$method:http`
```hoon
@ -228,6 +280,8 @@ An ordered list of HTTP headers. The `key` is the header name e.g `'Content-Type
An HTTP method.
---
### `$request:http`
```hoon
@ -241,6 +295,8 @@ An HTTP method.
A single HTTP request. The [$method:http](#methodhttp) is the HTTP method, the `url` is the unescaped URL, the [$header-list:http](#header-listhttp) contains the HTTP headers of the request and the `body` is the actual data. An `octs` is just `[p=@ud q=@]` where `p` is the byte-length of `q`, the data.
---
### `$response-header:http`
```hoon
@ -252,6 +308,8 @@ A single HTTP request. The [$method:http](#methodhttp) is the HTTP method, the `
The status code and [$header-list:http](#header-listhttp) of an HTTP response.
---
### `$http-event:http`
```hoon
@ -275,6 +333,8 @@ Urbit treats Earth's HTTP servers as pipes, where Urbit sends or receives one or
Calculation of control headers such as `'Content-Length'` or `'Transfer-Encoding'` should be performed at a higher level; this structure is merely for what gets sent to or received from Earth.
---
### `$simple-payload:http`
```hoon
@ -286,3 +346,5 @@ Calculation of control headers such as `'Content-Length'` or `'Transfer-Encoding
```
A simple, one-event response used for generators. The [$reponse-header:http](#response-headerhttp) contains the status code and HTTP headers. The `octs` in the `data` contains the body of the response and is a `[p=@ud q=@]` where `p` is the byte-length of `q`, the data.
---

60
content/reference/arvo/eyre/tasks.md
View File

@ -23,6 +23,8 @@ The `insecure` field is the HTTP port and `secure` is the optional HTTPS port.
Eyre returns no `gift` in response to a `%live` `task`.
---
## `%rule`
```hoon
@ -37,6 +39,8 @@ The [$http-rule](/reference/arvo/eyre/data-types#http-rule) is either tagged wit
Eyre returns no `gift` in response to a `%rule` `task`.
---
## `%request`
```hoon
@ -51,6 +55,8 @@ The `secure` field says whether it's over HTTPS. The `address` is the IP address
Eyre may `pass` a `%response` `gift` on the appropriate `duct` depending on the contents of the `%request`, state of the connection, and other factors.
---
## `%request-local`
```hoon
@ -63,6 +69,8 @@ This `task` is how Eyre receives an inbound HTTP request over the local loopback
Eyre may `pass` a `%response` `gift` on the appropriate `duct` depending on the contents of the `%request`, state of the connection, and other factors.
---
## `%cancel-request`
```hoon
@ -77,6 +85,8 @@ This `task` takes no arguments.
Eyre may `pass` a `%response` `gift` on the appropriate `duct` depending on the state of the connection and other factors.
---
## `%connect`
```hoon
@ -111,6 +121,8 @@ The `accepted` field says whether the binding succeeded and the `binding` is the
See the [Agents: Direct HTTP](/reference/arvo/eyre/guide#agents-direct-http) section of the [Guide](/reference/arvo/eyre/guide) document for an example.
---
## `%serve`
```hoon
@ -147,6 +159,8 @@ Eyre will return a `%bound` `gift` as described at the end of the [%connect](#co
See the [Generators](/reference/arvo/eyre/guide#generators) section of the [Guide](/reference/arvo/eyre/guide) document for an example.
---
## `%disconnect`
```hoon
@ -161,6 +175,8 @@ The [$binding](/reference/arvo/eyre/data-types#binding) is the URL path and doma
Eyre returns no `gift` in response to a `%disconnect` `task`.
---
## `%code-changed`
```hoon
@ -210,3 +226,47 @@ Eyre returns no `gift` in response to a `%reject-origin` `task`.
#### Example
See the [Managing CORS Origins](/reference/arvo/eyre/guide#managing-cors-origins) section of the [Guide](/reference/arvo/eyre/guide) document for an example.
---
## `%set-response`
```hoon
[%set-response url=@t entry=(unit cache-entry)]
```
This `task` tells Eyre to set a cache entry for a URL path. Adding entries to
Eyre's cache will make them much faster to load, and more capable of handling
many connections.
The `url` field is the URL path you want to bind with the cache entry. Note this
will just be the URL path as a cord like `'/foo/bar/baz'`, it does not include
the host, etc.
The `entry` field is a
[`$cache-entry`](/reference/arvo/eyre/data-types#cache-entry) in a `unit`. If
the unit is null, the specified `url` will be unbound and the cache entry
removed. If non-null, the given `entry` will be added to the cache (or updated
if the binding already exists).
Each time the entry for a URL path is changed, its revision number will be
incremented.
See the [`$cache-entry`](/reference/arvo/eyre/data-types#cache-entry) entry in
Eyre's type reference for more details of the entry itself.
#### Returns
Eyre gives a `%grow` `gift` in response to a `%set-response` `task`. A `%grow`
`gift` looks like:
```hoon
[%grow =path]
```
The `path` will be of the format `/cache/[revision]/[url]`, for example
`/cache/12/~~~2f.foo~2f.bar`. The revision number is incremented each time the
entry is updated, including if it's removed, and is in `@ud` format. The url
element uses `%t` [`++scot`](/reference/hoon/stdlib/4m#scot) encoding, so will
need to be decoded with `%t` [`++slav`](/reference/hoon/stdlib/4m#slav).
---