mirror of
https://github.com/urbit/developers.urbit.org.git
synced 2024-09-11 13:55:59 +03:00
Merge pull request #363 from urbit/add-eyre-cache-tasks
add %set-response task and cache-entry type to eyre ref for 413
This commit is contained in:
commit
5b958dc41a
@ -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.
|
||||
|
||||
---
|
||||
|
@ -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).
|
||||
|
||||
---
|
||||
|
Loading…
Reference in New Issue
Block a user