mirror of
https://github.com/urbit/developers.urbit.org.git
synced 2024-09-11 13:55:59 +03:00
update beacon docs to reflect beacon changes
This commit is contained in:
parent
89c859b76d
commit
4bd13a0e24
@ -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).
|
||||
|
||||
|
@ -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
|
||||
```
|
||||
|
||||
---
|
||||
|
@ -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
|
||||
```
|
||||
|
||||
---
|
||||
|
@ -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"
|
||||
},
|
||||
|
Loading…
Reference in New Issue
Block a user