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

update beacon docs to reflect beacon changes

Browse Source
This commit is contained in:
Tinnus Napbus 2023-03-27 22:01:22 +13:00
parent 89c859b76d
commit 4bd13a0e24
4 changed files with 459 additions and 262 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

134
content/reference/additional/beacon/overview.md
View File

@ -28,7 +28,7 @@ quickly go over how the system works.
6. The user of `~sampel-palnet` clicks "Approve" in Sentinel.
7. Sentinel on `~sampel-palnet` sends an update to Beacon on `~master` saying
the request was approved.
8. Beacon notififies `example.com` that the request was authorized.
8. Beacon notifies `example.com` that the request was authorized.
9. `example.com` logs the user in.
## Beacon Basics
@ -53,23 +53,22 @@ cancel an existing request. The `new` action looks something like this:
```json
{
"new": {
"stamp": 1666795723664000000,
"id": "2321f509-316c-4545-a838-4740eed86584",
"request": {
"ship": "sampel-palnet",
"turf": "example.com",
"user": "foobar123",
"code": 123456,
"msg": "blah blah blah",
"expire": 1666882123664
"expire": 1679788361389
"time": 1679787461389
}
}
}
```
The [`stamp`](/reference/additional/beacon/types#stamp) field is the request ID
and is typically the current time in nanoseconds since the Unix epoch. Note it's
*nanoseconds* - this extra precision is because every request needs a unique
`stamp` and collisions are less likely to occur this way.
The [`id`](/reference/additional/beacon/types#id) field is a random unique
ID for the request, and must be a v4 UUID (variant 1, RFC 4122/DCE 1.1).
The fields in the [`request`](/reference/additional/beacon/types#request) are as
follows:
@ -92,10 +91,12 @@ follows:
want. You might like to include things like the IP address of the login
request and the browser it came from. It's up to you.
- `expire`: This is the time the request should expire, in milliseconds since
the Unix epoch. Note it's *milliseconds*, not nanoseconds like the `stamp`.
You can have it expire whenever you want, but setting it unreasonably soon
(like seconds) may mean the user can't get to it in time, especially if
there's network latency. At least a few minutes from now is a good idea.
the Unix epoch. You can have it expire whenever you want, but setting it
unreasonably soon (like seconds) may mean the user can't get to it in time,
especially if there's network latency. At least a few minutes from now is a
good idea.
- `time`: This is the timestamp of the request in milliseconds since the Unix
epoch. You would typically just set it to now.
### Updates
@ -107,21 +108,22 @@ looks like this:
```json
{
"entry": {
"stamp": 1667212978424000000,
"id": "2321f509-316c-4545-a838-4740eed86584",
"request": {
"expire": 1667213278424,
"code": 123456,
"turf": "localhost",
"ship": "zod",
"turf": "localhost",
"user": "@user123",
"code": 123456,
"msg": "blah blah blah",
"user": "@user123"
"expire": 1667213278424,
"time": 1679787461389
},
"result": "sent"
}
}
```
It contains the [`stamp`](/reference/additional/beacon/types#stamp) and
It contains the [`id`](/reference/additional/beacon/types#id) and
[`request`](/reference/additional/beacon/types#request) from the `new` action
above, and additionally shows the initial status in the
[`result`](/reference/additional/beacon/types#result) field. This will normally
@ -133,7 +135,7 @@ After it's been sent you'll get [`status`](/reference/additional/beacon/types#st
```json
{
"status": {
"stamp": 1667213952904000000,
"id": "2321f509-316c-4545-a838-4740eed86584",
"result": "yes"
}
}
@ -142,7 +144,7 @@ After it's been sent you'll get [`status`](/reference/additional/beacon/types#st
Assuming it was initally `"sent"`, you'll get an update with a `"got"`
[`result`](/reference/additional/beacon/types#result) when the user receives it
(but hasn't yet approved or denied it). If they approve it, you'll then get a
`"yes"` update, and if they deny it you'll get `"no"`. If it expires before they
`"yes"` update, or if they deny it you'll get `"no"`. If it expires before they
receive it or before they approve/deny it, you'll get an `"expire"` update. If
there was an error in them receiving the request or your Beacon couldn't
subscribe for the result, you'll get an `"error"` update. If you cancelled the
@ -164,15 +166,15 @@ will do the same, but they'll also give you initial state. For each of these,
there is a path to receive all updates, and there are also sub-paths to filter
by [`turf`](/reference/additional/beacon/types#turf) (domain),
[`ship`](/reference/additional/beacon/types#ship) and
[`stamp`](/reference/additional/beacon/types#stamp). Additionally, for each
sub-path, you can specify a "since" `stamp`, and only receive updates and
initial state for requests with `stamp`s *later* than the one you specify.
[`id`](/reference/additional/beacon/types#id). Additionally, for each
sub-path, you can specify a "since" time, and only receive updates and
initial state for requests with `time`s *later* than the one you specify.
If you're only handling a single site in Beacon, you can just subscribe to the
`/init/all` path, retreiving initial state and then further updates as they
occur. If your site loses connection to Beacon, you can just resubscribe to
`/init/all` to resync state, or, if you don't want all historical state, you
could subscribe to `/init/all/since/1666875948253000000` where the `stamp`
could subscribe to `/init/all/since/1679787461389 ` where the `time`
specified is the oldest time you think you could reasonably care about.
### Attestations
@ -193,18 +195,26 @@ like:
}
```
In order to generate a proof, you must make a scry request to the
[`/proof/[turf]`](/reference/additional/beacon/scry#proof[turf]) scry path. The
`turf` in the path is your domain. Note it *must* use `++wood` encoding as
described in the [reference for that
path](/reference/additional/beacon/scry#proof[turf]). Assuming your domain just
contains lowercase letters, numbers and hyphens, it's as simple as prepending
`~` to all dot separators like `foo~.example~.com` for `foo.example.com`.
The Beacon front-end includes a simple tool to generate a `manifest` for a
single domain and ship. You can access it by clicking on Beacon's tile in
Landscape.
Once you have the proof you can just put it in an array. The `manifest` is
allowed to contain multiple proofs for the same ship, including different
`live`s (key revisions), as well as for multiple different ships and domains.
Sentinel will try find the best case with the following priority:
Alternatively, you can make a scry request to the
[`/proof/[turf]`](/reference/additional/beacon/scry#proof[turf]) scry path and
then programmatically put resulting proof(s) in a `manifest` array and serve
them on the `/.well-known/...` path. The `turf` in the path is your domain.
{% callout %}
[If your domain contains special characters, see the note at the bottom.](#additional note)
{% /callout %}
The `manifest` is allowed to contain multiple proofs for the same ship,
including different `live`s (key revisions), as well as for multiple different
ships and domains. Sentinel will try find the best case with the following
priority:
1. Valid signature at current life.
2. Invalid signature at current life.
@ -232,9 +242,59 @@ icon and a warning as described above.
{% callout %}
**Important note:**
It cannot follow relative redirect URLs - redirects MUST be absolute URLs
Sentinel cannot follow relative redirect URLs - redirects MUST be absolute URLs
including protocol.
{% /callout %}
## Additional note
The manifest generator along with the `/proof/[turf]` scry path and `turf`
subscription paths expect a domain with only lowercase `a-z`, `0-9`, `-` and
`.` separators. If your domain contains other characters, you'll have to use
the altenative `wood` paths with `++wood` encoding.
Here's an example implementation of `++wood` encoding:
```javascript
// encode the string into @ta-safe format, using logic from +wood.
// for example, 'some Chars!' becomes '~.some.~43.hars~21.'
//
export function stringToTa(str: string): string {
let out = "";
for (let i = 0; i < str.length; i++) {
const char = str[i];
let add = "";
switch (char) {
case " ":
add = ".";
break;
case ".":
add = "~.";
break;
case "~":
add = "~~";
break;
default:
const charCode = str.charCodeAt(i);
if (
(charCode >= 97 && charCode <= 122) || // a-z
(charCode >= 48 && charCode <= 57) || // 0-9
char === "-"
) {
add = char;
} else {
// TODO behavior for unicode doesn't match +wood's,
// but we can probably get away with that for now.
add = "~" + charCode.toString(16) + ".";
}
}
out = out + add;
}
return out;
}
```
You might also like to look at the Hoon reference for the
`++wood` function [here](/reference/hoon/stdlib/4b#wood).

209
content/reference/additional/beacon/scry.md
View File

@ -14,18 +14,26 @@ Make a [`proof`](/reference/additional/beacon/types#proof) for the given
`<domain>/.well-known/appspecific/org.urbit.beacon.json`. Sentinel uses it to
validate requests.
{% callout %}
#### Returns
**Important**
A [`proof`](/reference/additional/beacon/types#proof).
When encoding a `turf` (domain) in a subscription or scry path, you **must** use
`++wood` encoding as described in [this
function](https://github.com/urbit/urbit/blob/master/pkg/npm/api/lib/lib.ts#L207-L242),
except without the leading `~.`. If your domain does not contain unusual
characters, just lowercase letters, numbers and hyphens, you can just put a
tilde (`~`) before each dot separator rather than using the full function above.
#### Example
{% /callout %}
```
/proof/example.com
```
---
## `/proof/wood/[turf]`
Make a [`proof`](/reference/additional/beacon/types#proof) for the given
[`++wood`-encoded](/reference/additional/beacon/overview#additional-note)
[`turf`](/reference/additional/beacon/types#turf) (domain). This is put in a
[`manifest`](/reference/additional/beacon/types#manifest) and published at
`<domain>/.well-known/appspecific/org.urbit.beacon.json`. Sentinel uses it to
validate requests.
#### Returns
@ -34,7 +42,7 @@ A [`proof`](/reference/additional/beacon/types#proof).
#### Example
```
/proof/example~.com
/proof/example.com
```
---
@ -50,10 +58,10 @@ containing the current state.
---
## `/all/since/[stamp]`
## `/all/since/[time]`
Get all requests later than the specified
[`stamp`](/reference/additional/beacon/types#stamp), and their statuses.
Get all requests later than the specified Unix millisecond time, and their
statuses.
#### Returns
@ -64,15 +72,15 @@ current state of requests later than the one specified.
#### Example
```
/all/since/1666875948253000000
/all/since/1678658855227
```
---
## `/all/before/[stamp]`
## `/all/before/[time]`
Get all requests before the specified
[`stamp`](/reference/additional/beacon/types#stamp), and their statuses.
Get all requests before the specified Unix millisecond time, and their
statuses.
#### Returns
@ -82,26 +90,78 @@ containing the current state of requests earlier than the one specified.
#### Example
```
/all/before/1666875948253000000
/all/before/1678658855227
```
---
## `/ship/[ship]`
Get the state of all existing requests for the specifed
[`ship`](/reference/additional/beacon/types#ship).
#### Returns
You'll receive an [`initShip`](/reference/additional/beacon/types#initship)
update containing all requests for the specified `ship`, and their statuses.
#### Example
Note the leading `~` is omitted:
```
/ship/sampel-palnet
```
---
## `/ship/[ship]/since/[time]`
Get the state of all existing requests for the specifed
[`ship`](/reference/additional/beacon/types#ship) later than the specified Unix millisecond time.
#### Returns
You'll receive an [`initShip`](/reference/additional/beacon/types#initship)
update containing all entries for the specified `ship` with `time `s later than
the one specified.
#### Example
```
/ship/sampel-palnet/since/1678658855227
```
---
## `/ship/[ship]/before/[time]`
Get the state of all existing requests for the specifed
[`ship`](/reference/additional/beacon/types#ship) earlier than the specified Unix millisecond time.
#### Returns
You'll receive an [`initShip`](/reference/additional/beacon/types#initship)
update containing all entries for the specified `ship` with `time `s before the
one specified.
#### Example
```
/ship/sampel-palnet/before/1678658855227
```
---
## `/turf/[turf]`
Get the state of all existing requests for the specifed
[`turf`](/reference/additional/beacon/types#turf) (domain).
{% callout %}
**Important**
When encoding a `turf` (domain) in a subscription or scry path, you **must** use
`++wood` encoding as described in [this
function](https://github.com/urbit/urbit/blob/master/pkg/npm/api/lib/lib.ts#L207-L242),
except without the leading `~.`. If your domain does not contain unusual
characters, just lowercase letters, numbers and hyphens, you can just put a
tilde (`~`) before each dot separator rather than using the full function above.
If your domain contains characters apart from `a-z`, `0-9`, `-` and `.`
separators, see the `/turf/wood/[turf]` path instead.
{% /callout %}
@ -113,138 +173,126 @@ update containing all requests for the specified `turf`, and their statuses.
#### Example
```
/turf/example~.com
/turf/example.com
```
---
## `/turf/[turf]/since/[stamp]`
## `/turf/[turf]/since/[time]`
Get the state of all existing requests for the specifed
[`turf`](/reference/additional/beacon/types#turf) (domain) later than the
specified [`stamp`](/reference/additional/beacon/types#stamp).
specified Unix millisecond time.
{% callout %}
**Important**
When encoding a `turf` (domain) in a subscription or scry path, you **must** use
`++wood` encoding as described in [this
function](https://github.com/urbit/urbit/blob/master/pkg/npm/api/lib/lib.ts#L207-L242),
except without the leading `~.`. If your domain does not contain unusual
characters, just lowercase letters, numbers and hyphens, you can just put a
tilde (`~`) before each dot separator rather than using the full function above.
If your domain contains characters apart from `a-z`, `0-9`, `-` and `.`
separators, see the `/turf/wood/[turf]/since/[time]` path instead.
{% /callout %}
#### Returns
You'll receive an [`initTurf`](/reference/additional/beacon/types#initturf)
update containing all entries with `stamp `s later than the one specified.
update containing all entries with timestamps later than the one specified.
#### Example
```
/turf/example~.com/since/1666875948253000000
/turf/example.com/since/1678658855227
```
---
## `/turf/before/[stamp]`
## `/turf/[turf]/before/[time]`
Get the state of all existing requests for the specifed
[`turf`](/reference/additional/beacon/types#turf) (domain) earlier than the
specified [`stamp`](/reference/additional/beacon/types#stamp).
specified Unix millisecond time.
{% callout %}
**Important**
When encoding a `turf` (domain) in a subscription or scry path, you **must** use
`++wood` encoding as described in [this
function](https://github.com/urbit/urbit/blob/master/pkg/npm/api/lib/lib.ts#L207-L242),
except without the leading `~.`. If your domain does not contain unusual
characters, just lowercase letters, numbers and hyphens, you can just put a
tilde (`~`) before each dot separator rather than using the full function above.
If your domain contains characters apart from `a-z`, `0-9`, `-` and `.`
separators, see the `/turf/wood/[turf]/before/[time]` path instead.
{% /callout %}
#### Returns
You'll receive an [`initTurf`](/reference/additional/beacon/types#initturf)
update containing all entries for the specified `turf` (domain) with
[`stamp`](/reference/additional/beacon/types#stamp)s earlier than the one
specified.
update containing all entries for the specified `turf` (domain) with timestamps
earlier than the one specified.
#### Example
```
/turf/example~.com/before/1666875948253000000
/turf/example.com/before/1678658855227
```
---
## `/ship/[ship]`
## `/turf/wood/[turf]`
Get the state of all existing requests for the specifed
[`ship`](/reference/additional/beacon/types#turf).
[`turf`](/reference/additional/beacon/types#turf) (domain), with [`++wood` encoding](/reference/additional/beacon/overview#additonal-note).
#### Returns
You'll receive an [`initShip`](/reference/additional/beacon/types#initturf)
update containing all requests for the specified `ship`, and their statuses.
You'll receive an [`initTurf`](/reference/additional/beacon/types#initturf)
update containing all requests for the specified `turf`, and their statuses.
#### Example
```
/ship/sampel-palnet
/turf/wood/example~.com
```
---
## `/ship/[ship]/since/[stamp]`
## `/turf/wood/[turf]/since/[time]`
Get the state of all existing requests for the specifed
[`ship`](/reference/additional/beacon/types#ship) later than the specified
[`stamp`](/reference/additional/beacon/types#stamp).
[`turf`](/reference/additional/beacon/types#turf) (domain) later than the
specified Unix millisecond time. With [`++wood`
encoding](/reference/additional/beacon/overview#additonal-note).
#### Returns
You'll receive an [`initShip`](/reference/additional/beacon/types#initship)
update containing all entries for the specified `ship` with `stamp `s later than
the one specified.
You'll receive an [`initTurf`](/reference/additional/beacon/types#initturf)
update containing all entries with timestamps later than the one specified.
#### Example
```
/ship/sampel-palnet/since/1666875948253000000
/turf/wood/example~.com/since/1678658855227
```
---
## `/ship/[ship]/before/[stamp]`
## `/turf/wood/[turf]/before/[time]`
Get the state of all existing requests for the specifed
[`ship`](/reference/additional/beacon/types#ship) earlier than the specified
[`stamp`](/reference/additional/beacon/types#stamp).
[`turf`](/reference/additional/beacon/types#turf) (domain) earlier than the
specified Unix millisecond time. With [`++wood`
encoding](/reference/additional/beacon/overview#additonal-note).
#### Returns
You'll receive an [`initShip`](/reference/additional/beacon/types#initship)
update containing all entries for the specified `ship` with `stamp `s before the
one specified.
You'll receive an [`initTurf`](/reference/additional/beacon/types#initturf)
update containing all entries for the specified `turf` (domain) with timestamps
earlier than the one specified.
#### Example
```
/ship/sampel-palnet/before/1666875948253000000
/turf/wood/example~.com/before/1678658855227
```
---
## `/stamp/[stamp]`
## `/id/[uuid]`
Get a particular request and its current status.
Get a particular request and its current status, by UUID.
#### Returns
@ -254,23 +302,24 @@ request in question and its current status.
#### Example
```
/stamp/1666875948253000000
/id/2321f509-316c-4545-a838-4740eed86584
```
---
## `/stamp/status/[stamp]`
## `/id/status/[time]`
Get the status of a particular request.
#### Returns
A [`status`](/reference/additional/beacon/types#status) update containing the status of the request with the specified [`stamp`](/reference/additional/beacon/types#stamp).
A [`status`](/reference/additional/beacon/types#status) update containing the status of the request with the specified [`id`](/reference/additional/beacon/types#id).
#### Example
```
/stamp/status/1666875948253000000
/x/id/status/01a618cc-0c65-4278-853b-21d9e1289b93
```
---

233
content/reference/additional/beacon/subs.md
View File

@ -22,21 +22,20 @@ You'll receive [`entry`](/reference/additional/beacon/types#entry) and
---
### `/new/all/since/[stamp]`
### `/new/all/since/[time]`
Subscribe for all new updates since the given
[`stamp`](/reference/additional/beacon/types#stamp).
Subscribe for all new updates since the given Unix millisecond time.
#### Returns
You'll receive [`entry`](/reference/additional/beacon/types#entry) and
[`status`](/reference/additional/beacon/types#status) updates for requests as
the occur, but only for those with `stamp`s later than the one specified.
the occur, but only for those with timestamps later than the one specified.
#### Example
```
/new/all/since/1666875948253000000
/new/all/since/1678658855227
```
---
@ -48,17 +47,67 @@ Subscribe for all new updates for the given
{% callout %}
**Important**
When encoding a `turf` (domain) in a subscription or scry path, you **must** use
`++wood` encoding as described in [this
function](https://github.com/urbit/urbit/blob/master/pkg/npm/api/lib/lib.ts#L207-L242),
except without the leading `~.`. If your domain does not contain unusual
characters, just lowercase letters, numbers and hyphens, you can just put a
tilde (`~`) before each dot separator rather than using the full function above.
If your domain contains characters apart from `a-z`, `0-9`, `-` and `.`
separators, see the `/new/turf/wood/[turf]` path instead.
{% /callout %}
#### Returns
You'll receive [`entry`](/reference/additional/beacon/types#entry) and
[`status`](/reference/additional/beacon/types#status) updates for requests as
they occur, as long as they're for the specified `turf`.
#### Example
For `example.com`:
```
/new/turf/example.com
```
For `foo.bar-baz.com`:
```
/new/turf/foo.bar-baz.com
```
---
### `/new/turf/[turf]/since/[time]`
Subscribe for all new updates for the given
[`turf`](/reference/additional/beacon/types#turf) (domain), since the given Unix millisecond time.
{% callout %}
If your domain contains characters apart from `a-z`, `0-9`, `-` and `.`
separators, see the `/new/turf/wood/[turf]/since/[time]` path instead.
{% /callout %}
#### Returns
You'll receive [`entry`](/reference/additional/beacon/types#entry) and
[`status`](/reference/additional/beacon/types#status) updates for requests as
they occur, as long as they're for the specified `turf` and their timestamp is
sooner than the one specified in the path.
#### Example
```
/new/turf/example.com/since/1678658855227
```
---
### `/new/turf/wood/[turf]`
Subscribe for all new updates for the given
[`turf`](/reference/additional/beacon/types#turf) (domain), with [`++wood`
encoding](/reference/additional/beacon/overview#additonal-note).
#### Returns
You'll receive [`entry`](/reference/additional/beacon/types#entry) and
@ -76,40 +125,29 @@ For `example.com`:
For `foo.bar-baz.com`:
```
/new/turf/foo~.bar-baz.com
/new/turf/foo~.bar-baz~.com
```
---
### `/new/turf/[turf]/since/[stamp]`
### `/new/turf/wood/[turf]/since/[time]`
Subscribe for all new updates for the given
[`turf`](/reference/additional/beacon/types#turf) (domain), since the given [`stamp`](/reference/additional/beacon/types#stamp).
{% callout %}
**Important**
When encoding a `turf` (domain) in a subscription or scry path, you **must** use
`++wood` encoding as described in [this
function](https://github.com/urbit/urbit/blob/master/pkg/npm/api/lib/lib.ts#L207-L242),
except without the leading `~.`. If your domain does not contain unusual
characters, just lowercase letters, numbers and hyphens, you can just put a
tilde (`~`) before each dot separator rather than using the full function above.
{% /callout %}
[`turf`](/reference/additional/beacon/types#turf) (domain), since the given Unix
millisecond time. With [`++wood`
encoding](/reference/additional/beacon/overview#additonal-note).
#### Returns
You'll receive [`entry`](/reference/additional/beacon/types#entry) and
[`status`](/reference/additional/beacon/types#status) updates for requests as
they occur, as long as they're for the specified `turf` and their `stamp` is
they occur, as long as they're for the specified `turf` and their timestamp is
sooner than the one specified in the path.
#### Example
```
/new/turf/example~.com/since/1666875948253000000
/new/turf/example~.com/since/1678658855227
```
---
@ -135,16 +173,16 @@ Note that the ship does not include the leading `~`:
---
### `/new/ship/[ship]/since/[stamp]`
### `/new/ship/[ship]/since/[time]`
Subscribe for all new updates for the given
[`ship`](/reference/additional/beacon/types#ship), since the given [`stamp`](/reference/additional/beacon/types#stamp).
[`ship`](/reference/additional/beacon/types#ship), since the given Unix millisecond time.
#### Returns
You'll receive [`entry`](/reference/additional/beacon/types#entry) and
[`status`](/reference/additional/beacon/types#status) updates for requests as
they occur, as long as they're for the specified `ship` and their `stamp` is
they occur, as long as they're for the specified `ship` and their timestamp is
sooner than the one specified in the path.
#### Example
@ -153,26 +191,26 @@ sooner than the one specified in the path.
Note that the ship does not include the leading `~`:
```
/new/ship/sampel-palnet/since/1666875948253000000
/new/ship/sampel-palnet/since/1678658855227
```
---
### `/new/stamp/[stamp]`
### `/new/id/[uuid]`
Subscribe for all new updates for the given
[`stamp`](/reference/additional/beacon/types#stamp).
[`id`](/reference/additional/beacon/types#id).
#### Returns
You'll receive [`entry`](/reference/additional/beacon/types#entry) updates and
any [`status`](/reference/additional/beacon/types#status) updates for the
request with the given [`stamp`] as they occur.
request with the given `id` as they occur.
#### Example
```
/new/stamp/1666875948253000000
/new/id/01a618cc-0c65-4278-853b-21d9e1289b93
```
---
@ -197,11 +235,11 @@ current state, and then you'll continue to receive
---
### `/init/all/since/[stamp]`
### `/init/all/since/[time]`
Subscribe to updates for requests that occurred after the specified
[`stamp`](/reference/additional/beacon/types#stamp), and get the existing state
of all requests with `stamp`s later than the one specified.
Subscribe to updates for requests that occurred after the specified Unix
millisecond time, and get the existing state of all requests with
timestamps later than the one specified.
#### Returns
@ -210,32 +248,26 @@ You'll initially receive an
current state of requests later than the one specified. After that, you'll
continue to receive [`entry`](/reference/additional/beacon/types#entry) and
[`status`](/reference/additional/beacon/types#status) updates as they occur, as
long as they're for requests whose `stamp`s are later than the one given.
long as they're for requests whose timestamps are later than the one given.
#### Example
```
/init/all/since/1666875948253000000
/init/all/since/1678658855227
```
---
### `/init/turf/[turf]`
Subscribe to updates for requests pertaining to the given
[`turf`](/reference/additional/beacon/types#turf), and get the existing state of
all requests pertaining to that `turf`.
Get existing request state and subscribe to updates pertaining to the given
[`turf`](/reference/additional/beacon/types#turf).
{% callout %}
**Important**
When encoding a `turf` (domain) in a subscription or scry path, you **must** use
`++wood` encoding as described in [this
function](https://github.com/urbit/urbit/blob/master/pkg/npm/api/lib/lib.ts#L207-L242),
except without the leading `~.`. If your domain does not contain unusual
characters, just lowercase letters, numbers and hyphens, you can just put a
tilde (`~`) before each dot separator rather than using the full function above.
If your domain contains characters apart from `a-z`, `0-9`, `-` and `.`
separators, see the `/init/turf/wood/[turf]` path instead.
{% /callout %}
@ -251,28 +283,21 @@ long as they're for that `turf`.
#### Example
```
/init/turf/example~.com
/init/turf/example.com
```
---
### `/init/turf/[turf]/since/[stamp]`
### `/init/turf/[turf]/since/[time]`
Subscribe to updates for requests pertaining to the given
[`turf`](/reference/additional/beacon/types#turf), and get the existing state of
all requests pertaining to that `turf`, as long as the
[`stamp`](/reference/additional/beacon/types#stamp) is later than the one given.
Get existing request state and subscribe to updates pertaining to the given
[`turf`](/reference/additional/beacon/types#turf), for requests whose timestamps
are later than the Unix millisecond time given.
{% callout %}
**Important**
When encoding a `turf` (domain) in a subscription or scry path, you **must** use
`++wood` encoding as described in [this
function](https://github.com/urbit/urbit/blob/master/pkg/npm/api/lib/lib.ts#L207-L242),
except without the leading `~.`. If your domain does not contain unusual
characters, just lowercase letters, numbers and hyphens, you can just put a
tilde (`~`) before each dot separator rather than using the full function above.
If your domain contains characters apart from `a-z`, `0-9`, `-` and `.`
separators, see the `/init/turf/wood/[turf]/since/[time]` path instead.
{% /callout %}
@ -280,20 +305,69 @@ tilde (`~`) before each dot separator rather than using the full function above.
You'll initially receive an
[`initTurf`](/reference/additional/beacon/types#initturf) update containing the
current state of requests for the given `turf` with `stamp`s later than the
`stamp` given. After that, you'll continue to receive
current state of requests for the given `turf` with times later than the
given one. After that, you'll continue to receive
[`entry`](/reference/additional/beacon/types#entry) and
[`status`](/reference/additional/beacon/types#status) updates as they occur, as
long as they're for that `turf` and have `stamp`s later than the one specified.
long as they're for that `turf` and have timestamps later than the one
specified.
#### Example
```
/init/turf/example~.com/since/1666875948253000000
/init/turf/example.com/since/1678658855227
```
---
### `/init/turf/wood/[turf]`
Get existing state request state and subscribe to updates pertaining to the
given [`turf`](/reference/additional/beacon/types#turf). With [`++wood`
encoding](/reference/additional/beacon/overview#additonal-note).
#### Returns
You'll initially receive an
[`initTurf`](/reference/additional/beacon/types#initturf) update containing the
current state of requests for the given `turf`. After that, you'll continue to
receive [`entry`](/reference/additional/beacon/types#entry) and
[`status`](/reference/additional/beacon/types#status) updates as they occur, as
long as they're for that `turf`.
#### Example
```
/init/turf/wood/example~.com
```
---
### `/init/turf/wood/[turf]/since/[time]`
Get existing request state and subscribe to updates pertaining to the given
[`turf`](/reference/additional/beacon/types#turf), for requests whose timestamps
are later than the Unix millisecond time given. With [`++wood`
encoding](/reference/additional/beacon/overview#additonal-note).
#### Returns
You'll initially receive an
[`initTurf`](/reference/additional/beacon/types#initturf) update containing the
current state of requests for the given `turf` with timestamps later than the
given one. After that, you'll continue to receive
[`entry`](/reference/additional/beacon/types#entry) and
[`status`](/reference/additional/beacon/types#status) updates as they occur, as
long as they're for that `turf` and have timestamps later than the one
specified.
#### Example
```
/init/turf/example~.com/since/1678658855227
```
---
### `/init/ship/[ship]`
Subscribe to updates for requests pertaining to the given
@ -317,12 +391,12 @@ long as they're for that `ship`.
---
### `/init/ship/[ship]/since/[stamp]`
### `/init/ship/[ship]/since/[time]`
Subscribe to updates for requests pertaining to the given
[`ship`](/reference/additional/beacon/types#ship), and get the existing state of
all requests pertaining to that `ship`, as long as the
[`stamp`](/reference/additional/beacon/types#stamp) is later than the one given.
all requests pertaining to that `ship`, as long as the timestamp is later than
the Unix millisecond time given.
#### Returns
@ -332,12 +406,13 @@ current state of requests for the given `ship` with `stamp`s later than the
`stamp` given. After that, you'll continue to receive
[`entry`](/reference/additional/beacon/types#entry) and
[`status`](/reference/additional/beacon/types#status) updates as they occur, as
long as they're for that `ship` and have `stamp`s later than the one specified.
long as they're for that `ship` and have timestamps later than the one
specified.
#### Example
```
/init/ship/sampel-palnet/since/1666875948253000000
/init/ship/sampel-palnet/since/1678658855227
```
---

145
content/reference/additional/beacon/types.md
View File

@ -6,8 +6,8 @@ template = "doc.html"
## `logs`
A list of [`request`](#request)s, their [`stamp`](#stamp)s (IDs), and their
current [`result`](#result)s. These are given in the various initialization
A list of [`request`](#request)s, their [`id`](#id)s, and their current
[`result`](#result)s. These are given in the various initialization
[`updates`](#updates).
#### Example
@ -15,38 +15,41 @@ current [`result`](#result)s. These are given in the various initialization
```json
[
{
"stamp": 1666795723664000000,
"id": "7e16a2f5-b955-47c3-b921-da349c0e2c24",
"request": {
"ship": "zod",
"turf": "localhost",
"user": "foobar123",
"code": 123456,
"msg": "blah blah blah",
"expire": 1666882123664,
"expire": 1679820698574,
"time": 1679819798574
},
"result": "yes"
},
{
"stamp": 1666799618474000000,
"id": "d63971cc-453f-49a8-868f-02e2ff768ed2",
"request": {
"ship": "zod",
"turf": "localhost",
"user": "xyz",
"code": 123456,
"msg": null,
"expire": 1666886018474,
"expire": 1679820699556,
"time": 1679819799556
},
"result": "yes"
},
{
"stamp": 1666799624841000000,
"id": "587f6be9-1dca-4310-9239-ea541943f0e0",
"request": {
"ship": "zod",
"turf": "localhost",
"user": null,
"code": null,
"msg": "blah blah blah",
"expire": 1666886024841,
"expire": 1679820700233,
"time": 1679819800233
},
"result": "no"
}
@ -97,7 +100,8 @@ published at `<domain>/.well-known/appspecific/org.urbit.beacon.json` in a
An authorization request. The `user`, `code` and `msg` fields are all optional
and may be `null` if not used. The `expire` field is the date-time that the
request should expire, as milliseconds since the Unix Epoch.
request should expire, as milliseconds since the Unix Epoch. The `time` field
is the timestamp of the request - you'd typically use now.
#### Examples
@ -108,7 +112,8 @@ request should expire, as milliseconds since the Unix Epoch.
"user": "foo123",
"code": 1234,
"msg": "blah blah blah",
"expire": 1666955338448
"expire": 1679820700233,
"time" 1679819800233,
}
```
@ -119,7 +124,8 @@ request should expire, as milliseconds since the Unix Epoch.
"user": null,
"code": null,
"msg": null,
"expire": 1666955338448
"expire": 1679820700233,
"time" 1679819800233,
}
```
@ -134,7 +140,8 @@ The status of an authorization request. It may be one of:
* `"expire"` - The request expired without the user approving or denying it.
* `"got"` - The user's ship received the request, but they have not yet approved
or denied it.
* `"sent"` - Beacon has sent the request; the user's ship has not yet received it.
* `"sent"` - Beacon has sent the request; the user's ship has not yet confirmed
receipt.
* `"abort"` - You have given beacon a [`cancel`](#cancel) action, so the request
has been cancelled.
* `"error"` - The request failed. This will occur if the user's ship rejected
@ -185,22 +192,19 @@ of a particular site.
---
## `stamp`
## `id`
A request ID. This is a date-time as the number of **nanoseconds** since the
Unix Epoch. Each request must have a unique `stamp`, and requests are ordered by
this `stamp`. You would typically use the date-time when the request occurred.
A request ID. The [`id`](/reference/additional/beacon/types#id) field is a
random unique ID for the request, and must be a v4 UUID (variant 1, RFC
4122/DCE 1.1).
Nanoseconds are used rather than milliseconds to make collisions less likely if
two requests occur at roughly the same time. If you don't need or don't have
this much precision you can just multiply the Unix millisecond time by a million
or just fudge the less significant digits. The important thing is that it's
unique for each request.
Note this is decoded into a 122-bit `@ux` atom by `%beacon` - the UUID form is
only used in JSON, scry paths and subscription paths.
#### Example
```json
1666953051302000000
"6360904f-7645-4747-91a1-8d7844f11d18"
```
---
@ -220,21 +224,22 @@ one. These are given to Beacon as pokes.
### `new`
Initiate a new authorization request. The `new` action contains a
[`request`](#request) structure and a [`stamp`](#stamp) (request ID).
[`request`](#request) structure and a request [`id`](#id).
#### Example
```json
{
"new": {
"stamp": 1666795723664000000,
"id": "6360904f-7645-4747-91a1-8d7844f11d18",
"request": {
"ship": "zod",
"turf": "localhost",
"user": "foobar123",
"code": 123456,
"msg": "blah blah blah",
"expire": 1666882123664
"expire": 1679820700233,
"time" 1679819800233
}
}
}
@ -242,13 +247,13 @@ Initiate a new authorization request. The `new` action contains a
### `cancel`
Cancel an existing request. The [`stamp`](#stamp) in the ID of the request you
Cancel an existing request. The [`id`](#id) in the ID of the request you
want to cancel.
#### Example
```json
{"cancel": {"stamp": 1666795723664000000}}
{"cancel": {"id": "6360904f-7645-4747-91a1-8d7844f11d18"}}
```
---
@ -259,7 +264,8 @@ The types of event/update that beacon can send back to you.
### `entry`
This will be sent back to you whenever you make a new request with a [`new`](#new) action. It contains the [`stamp`](#stamp) (request ID),
This will be sent back to you whenever you make a new request with a
[`new`](#new) action. It contains the request [`id`](#id),
[`request`](#request) and initial [`result`](#result). The initial result will
typically be `sent`, unless you specified an expiration time before the current
time, in which case it'll be `expire`.
@ -269,14 +275,15 @@ time, in which case it'll be `expire`.
```json
{
"entry": {
"stamp": 1667212978424000000,
"id": "6360904f-7645-4747-91a1-8d7844f11d18",
"request": {
"expire": 1667213278424,
"code": 123456,
"turf": "localhost",
"ship": "zod",
"msg": "blah blah blah",
"user": "@user123"
"user": "@user123",
"expire": 1679820700233,
"time" 1679819800233
},
"result": "sent"
}
@ -287,15 +294,15 @@ time, in which case it'll be `expire`.
A `status` update will be sent back whenever the status of a request changes,
for example if the user receives the request, the user approves or denies the
request, the request expires, etc. It contains a [`stamp`](#stamp) (request ID)
and a [`result`](#result).
request, the request expires, etc. It contains a request [`id`](#id) and a
[`result`](#result).
#### Examples
```json
{
"status": {
"stamp": 1667213952904000000,
"id": "6360904f-7645-4747-91a1-8d7844f11d18",
"result": "yes"
}
}
@ -304,7 +311,7 @@ and a [`result`](#result).
```json
{
"status": {
"stamp": 1667213954564000000,
"id": "6360904f-7645-4747-91a1-8d7844f11d18",
"result": "got"
}
}
@ -313,13 +320,13 @@ and a [`result`](#result).
### `initAll`
This is sent as the inital update when you first subscribe to one of the
`/init/all/...` paths. It's also returned by some of the scry paths. It contains
existing entries, possibly limited to entries before or after a specific
[`stamp`](#stamp).
`/init/all/...` paths. It's also returned by some of the scry paths. It
contains existing entries, possibly limited to entries before or after a
specific timestamp.
It contains a [`logs`](#logs) field with the entries themselves, and also
`before` and `after` fields which will either contain [`stamp`](#stamp)s or else
be null if no such limits were specified.
`before` and `after` fields which will either contain Unix millisecond times or
else be null if no such limits were specified.
#### Example
@ -330,26 +337,28 @@ be null if no such limits were specified.
"before": null,
"logs": [
{
"stamp": 1666795723664000000,
"id": "0782ebea-e8d3-4c6a-bf1c-5c336c82a0d3",
"request": {
"expire": 1666882123664,
"code": 123456,
"turf": "localhost",
"ship": "zod",
"msg": "blah blah",
"user": "foobar123"
"user": "foobar123",
"expire": 1679827515744,
"time": 1679826615744
},
"result": "yes"
},
{
"stamp": 1666799618474000000,
"id": "4c54c5d9-6584-4d3b-ab62-e55f5f2033c4",
"request": {
"expire": 1666886018474,
"code": 123456,
"turf": "localhost",
"ship": "zod",
"msg": "foo bar baz",
"user": null
"user": null,
"expire": 1679827571421,
"time": 1679826671421
},
"result": "no"
},
@ -363,12 +372,12 @@ be null if no such limits were specified.
This is sent as the inital update when you first subscribe to one of the
`/init/turf/...` paths. It's also returned by some of the scry paths. It
contains existing entries for a specific [`turf`](#turf) (domain), possibly
limited to entries before or after a specific [`stamp`](#stamp).
limited to entries before or after a specific timestamp.
It contains a [`turf`](#turf) field showing which domain it's for, a
[`logs`](#logs) field with the entries themselves, and also `before` and `after`
fields which will either contain [`stamp`](#stamp)s or else be null if no such
limits were specified.
[`logs`](#logs) field with the entries themselves, and also `before` and
`after` fields which will either contain Unix millisecond timestamps or else be
null if no such limits were specified.
#### Example
@ -380,26 +389,28 @@ limits were specified.
"before": null,
"logs": [
{
"stamp": 1666795723664000000,
"id": "0782ebea-e8d3-4c6a-bf1c-5c336c82a0d3",
"request": {
"expire": 1666882123664,
"code": 123456,
"turf": "localhost",
"ship": "zod",
"msg": "blah blah",
"user": "foobar123"
"user": "foobar123",
"expire": 1679827515744,
"time": 1679826615744
},
"result": "yes"
},
{
"stamp": 1666799618474000000,
"id": "4c54c5d9-6584-4d3b-ab62-e55f5f2033c4",
"request": {
"expire": 1666886018474,
"code": 123456,
"turf": "localhost",
"ship": "zod",
"msg": "foo bar baz",
"user": null
"user": null,
"expire": 1679827571421,
"time": 1679826671421
},
"result": "no"
},
@ -413,12 +424,12 @@ limits were specified.
This is sent as the inital update when you first subscribe to one of the
`/init/ship/...` paths. It's also returned by some of the scry paths. It
contains existing entries for a specific [`ship`](#ship), possibly limited to
entries before or after a specific [`stamp`](#stamp).
entries before or after a specific timestamp.
It contains a [`ship`](#ship) field showing which ship it's for, a
[`logs`](#logs) field with the entries themselves, and also `before` and `after`
fields which will either contain [`stamp`](#stamp)s or else be null if no such
limits were specified.
[`logs`](#logs) field with the entries themselves, and also `before` and
`after` fields which will either contain Unix millisecond timestamps or else be
null if no such limits were specified.
#### Example
@ -430,26 +441,28 @@ limits were specified.
"before": null,
"logs": [
{
"stamp": 1666795723664000000,
"id": "0782ebea-e8d3-4c6a-bf1c-5c336c82a0d3",
"request": {
"expire": 1666882123664,
"code": 123456,
"turf": "localhost",
"ship": "zod",
"msg": "blah blah",
"user": "foobar123"
"user": "foobar123",
"expire": 1679827515744,
"time": 1679826615744
},
"result": "yes"
},
{
"stamp": 1666799618474000000,
"id": "4c54c5d9-6584-4d3b-ab62-e55f5f2033c4",
"request": {
"expire": 1666886018474,
"code": 123456,
"turf": "localhost",
"ship": "zod",
"msg": "foo bar baz",
"user": null
"user": null,
"expire": 1679827571421,
"time": 1679826671421
},
"result": "no"
},