@minca/core 0.1.17 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -1
- package/dist/files/space-files.d.ts +2 -2
- package/dist/files/space-files.d.ts.map +1 -1
- package/dist/files/space-files.js +7 -5
- package/dist/files/space-files.js.map +1 -1
- package/dist/inbox/names.d.ts +1 -1
- package/dist/inbox/names.js +1 -1
- package/dist/index.d.ts +3 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -1
- package/dist/node/actions.d.ts +3 -0
- package/dist/node/actions.d.ts.map +1 -1
- package/dist/node/actions.js.map +1 -1
- package/dist/node/api.d.ts +1 -0
- package/dist/node/api.d.ts.map +1 -1
- package/dist/node/api.js +1 -0
- package/dist/node/api.js.map +1 -1
- package/dist/node/carrier.js +1 -1
- package/dist/node/carrier.js.map +1 -1
- package/dist/node/index.d.ts +1 -1
- package/dist/node/index.d.ts.map +1 -1
- package/dist/node/node-contacts.d.ts.map +1 -1
- package/dist/node/node-contacts.js +1 -0
- package/dist/node/node-contacts.js.map +1 -1
- package/dist/node/node-records.d.ts.map +1 -1
- package/dist/node/node-records.js +6 -1
- package/dist/node/node-records.js.map +1 -1
- package/dist/node/node.d.ts.map +1 -1
- package/dist/node/node.js +13 -1
- package/dist/node/node.js.map +1 -1
- package/dist/node/remote.d.ts.map +1 -1
- package/dist/node/remote.js +7 -1
- package/dist/node/remote.js.map +1 -1
- package/dist/node/space-runtime.d.ts +5 -3
- package/dist/node/space-runtime.d.ts.map +1 -1
- package/dist/node/space-runtime.js +3 -1
- package/dist/node/space-runtime.js.map +1 -1
- package/dist/node/types.d.ts +112 -36
- package/dist/node/types.d.ts.map +1 -1
- package/dist/node/watch-notifications.d.ts +6 -0
- package/dist/node/watch-notifications.d.ts.map +1 -1
- package/dist/node/watch-notifications.js +47 -9
- package/dist/node/watch-notifications.js.map +1 -1
- package/dist/query/types.d.ts +1 -0
- package/dist/query/types.d.ts.map +1 -1
- package/dist/query/types.js.map +1 -1
- package/dist/records/contract-builder.d.ts +22 -6
- package/dist/records/contract-builder.d.ts.map +1 -1
- package/dist/records/contract-builder.js.map +1 -1
- package/dist/schemas/automations.d.ts +6 -2
- package/dist/schemas/automations.d.ts.map +1 -1
- package/dist/schemas/automations.js.map +1 -1
- package/dist/schemas/connectors.d.ts +4 -3
- package/dist/schemas/connectors.d.ts.map +1 -1
- package/dist/schemas/connectors.js +4 -3
- package/dist/schemas/connectors.js.map +1 -1
- package/dist/schemas/library/media.js +1 -1
- package/dist/schemas/library/media.js.map +1 -1
- package/dist/session/account-hint.d.ts +2 -2
- package/dist/session/account-hint.d.ts.map +1 -1
- package/dist/session/account-hint.js +3 -3
- package/dist/session/account-hint.js.map +1 -1
- package/dist/session/auth.d.ts +7 -3
- package/dist/session/auth.d.ts.map +1 -1
- package/dist/session/auth.js.map +1 -1
- package/dist/session/connection.d.ts +18 -0
- package/dist/session/connection.d.ts.map +1 -1
- package/dist/session/connection.js +11 -0
- package/dist/session/connection.js.map +1 -1
- package/dist/session/index.d.ts +2 -2
- package/dist/session/index.d.ts.map +1 -1
- package/dist/session/index.js +2 -2
- package/dist/session/index.js.map +1 -1
- package/dist/storage/blob-store.d.ts +3 -0
- package/dist/storage/blob-store.d.ts.map +1 -1
- package/dist/types.d.ts +11 -2
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js.map +1 -1
- package/docs/README.md +86 -93
- package/docs/actions.md +213 -152
- package/docs/agents.md +198 -167
- package/docs/automations.md +296 -204
- package/docs/blueprints-and-guides.md +405 -311
- package/docs/bots.md +208 -134
- package/docs/building-an-app.md +86 -159
- package/docs/collections.md +248 -328
- package/docs/computed.md +112 -89
- package/docs/contacts.md +151 -112
- package/docs/contracts.md +299 -120
- package/docs/direct-messages.md +80 -65
- package/docs/inbox.md +138 -93
- package/docs/node.md +1081 -996
- package/docs/permissions.md +142 -0
- package/docs/proposing-collections.md +74 -55
- package/docs/query-format.md +150 -126
- package/docs/records-and-queries.md +205 -126
- package/docs/sign-in.md +487 -416
- package/docs/spaces.md +261 -246
- package/docs/standard-library.md +487 -526
- package/docs/storage.md +325 -348
- package/docs/usernames.md +164 -97
- package/docs/warrants.md +100 -67
- package/package.json +1 -6
- package/dist/elements/auth-styles.d.ts +0 -18
- package/dist/elements/auth-styles.d.ts.map +0 -1
- package/dist/elements/auth-styles.js +0 -206
- package/dist/elements/auth-styles.js.map +0 -1
- package/dist/elements/dom.d.ts +0 -29
- package/dist/elements/dom.d.ts.map +0 -1
- package/dist/elements/dom.js +0 -91
- package/dist/elements/dom.js.map +0 -1
- package/dist/elements/index.d.ts +0 -13
- package/dist/elements/index.d.ts.map +0 -1
- package/dist/elements/index.js +0 -11
- package/dist/elements/index.js.map +0 -1
- package/dist/elements/minca-auth.d.ts +0 -55
- package/dist/elements/minca-auth.d.ts.map +0 -1
- package/dist/elements/minca-auth.js +0 -768
- package/dist/elements/minca-auth.js.map +0 -1
package/docs/node.md
CHANGED
|
@@ -1,1090 +1,1175 @@
|
|
|
1
1
|
# The node
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
app-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
3
|
+
A node is what takes part in Minca for an account. It holds the account's
|
|
4
|
+
spaces, signs what it writes, checks what peers send, and keeps everything in
|
|
5
|
+
sync. Most apps never make one: the connection starts it for you
|
|
6
|
+
([building an app](building-an-app.md)). You make one yourself in a program
|
|
7
|
+
that holds the account's keys, such as a script, a server or a test.
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
import { createNode, deriveAccountKey, generateSeed, indexedDBStores, rootFromSeed } from '@minca/core';
|
|
11
|
+
|
|
12
|
+
const seed = generateSeed();
|
|
13
|
+
const { signer } = await rootFromSeed(seed);
|
|
14
|
+
|
|
15
|
+
const node = await createNode({
|
|
16
|
+
signer,
|
|
17
|
+
accountKey: await deriveAccountKey(seed),
|
|
18
|
+
stores: indexedDBStores('my-app'),
|
|
19
|
+
network: { relays: ['wss://relay.minca.social'] },
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
const space = await node.spaces.create({ name: 'Notes', visibility: 'private' });
|
|
23
|
+
await node.records.put(space.id, 'app.note', { text: 'Hello' });
|
|
24
|
+
```
|
|
12
25
|
|
|
13
26
|
## Configuration
|
|
14
27
|
|
|
15
|
-
`createNode(config)` takes
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
_Source: `packages/core/src/node/types.ts` (`NodeConfig`, `NodeNetworkConfig`, `CacheConfig`). Tests: `packages/core/tests/node.test.ts`, `packages/core/tests/caches.test.ts`._
|
|
28
|
+
`createNode(config)` takes a [`NodeConfig`](https://minca.dev/api/core/interfaces/NodeConfig/),
|
|
29
|
+
whose page gives each field's meaning and default. The sections below explain
|
|
30
|
+
the ones that work together: [root signers](#root-signers-and-notes),
|
|
31
|
+
[stores](#stores), [writer keys](#writer-keys) and
|
|
32
|
+
[holding part of a space](#holding-part-of-a-space).
|
|
33
|
+
|
|
34
|
+
### Collections the node knows
|
|
35
|
+
|
|
36
|
+
`collections` gives the node schemas to use when a space doesn't describe a
|
|
37
|
+
collection itself. Writes are checked against them, and reads are flagged
|
|
38
|
+
`conforms`. Nothing arriving from a peer is refused for its shape.
|
|
39
|
+
|
|
40
|
+
### Network options
|
|
41
|
+
|
|
42
|
+
`network` is a [`NodeNetworkConfig`](https://minca.dev/api/core/interfaces/NodeNetworkConfig/):
|
|
43
|
+
the relays where peers meet, always-on nodes to dial, hosts to look for the
|
|
44
|
+
account registry at, and more. Omitted, the node stays offline.
|
|
45
|
+
[The network](#the-network) says how the node uses them.
|
|
35
46
|
|
|
36
47
|
## Lifecycle
|
|
37
48
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
`
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
`
|
|
70
|
-
stopping sync and disconnecting its transports), closes the registry store,
|
|
71
|
-
and drops all event listeners. After `close()`, any call that needs a space
|
|
72
|
-
fails with `Node is closed`. Closing twice does nothing.
|
|
73
|
-
|
|
74
|
-
_Source: `packages/core/src/node/node.ts` (`createNode`, `close`). Tests: `packages/core/tests/node.test.ts`._
|
|
49
|
+
When it starts, a node picks its signing key: `sessionKey` if given, else one
|
|
50
|
+
claimed from `writerKey`, else a fresh P-256 key for this run. Its DID is
|
|
51
|
+
`node.sessionDid`. Then it asks the signer for a session note and waits. If
|
|
52
|
+
the signer refuses, `createNode` fails.
|
|
53
|
+
|
|
54
|
+
With an account key, the node also opens the account registry and makes its
|
|
55
|
+
spaces match it before `createNode` returns
|
|
56
|
+
([following the account](#following-the-account)).
|
|
57
|
+
|
|
58
|
+
A node acts for one account (`node.did`) and signs with one key for its whole
|
|
59
|
+
life. To act for another account, start another node.
|
|
60
|
+
|
|
61
|
+
### Revoking keys
|
|
62
|
+
|
|
63
|
+
`revokeKey(key, { spaces?, waitMs? })` revokes one of the account's keys, with
|
|
64
|
+
a cutoff at what that key wrote. By default it does this wherever the account
|
|
65
|
+
writes: every space it lists, its carry spaces, the contacts space and the
|
|
66
|
+
account registry. It says whether a peer took each revoke in within `waitMs`.
|
|
67
|
+
The account home calls it when you disconnect an app.
|
|
68
|
+
|
|
69
|
+
`revokeSelf()` does the same for the node's own key, and forgets a lasting
|
|
70
|
+
key at once. The account home calls it on sign-out.
|
|
71
|
+
|
|
72
|
+
A record is judged with no clock, so it is a revoke, not the note running out,
|
|
73
|
+
that ends what a key can write. An agent can't call either.
|
|
74
|
+
[Spec 01 §7.4](https://github.com/leifriksheim/minca/blob/main/spec/01-identity.md).
|
|
75
|
+
|
|
76
|
+
### Closing
|
|
77
|
+
|
|
78
|
+
`close()` stops renewing the note, closes every open space and the registry,
|
|
79
|
+
and drops all event listeners. After that, any call that needs a space fails
|
|
80
|
+
with `Node is closed`. Closing twice does nothing.
|
|
75
81
|
|
|
76
82
|
## Root signers and notes
|
|
77
83
|
|
|
78
|
-
A node never holds the root key. It
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
-
|
|
89
|
-
the
|
|
90
|
-
|
|
91
|
-
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
The audience and expiration are the far end's to pick, so it bounds
|
|
100
|
-
neither.
|
|
101
|
-
|
|
102
|
-
The **session note** a node asks for when it starts:
|
|
84
|
+
A node never holds the account's root key. It gets a **root signer**, which
|
|
85
|
+
hides where the key lives and is only asked for notes.
|
|
86
|
+
|
|
87
|
+
Its interface is [`RootSigner`](https://minca.dev/api/core/interfaces/RootSigner/): the
|
|
88
|
+
account's DID, and `delegate`, which issues a note from the account to a key.
|
|
89
|
+
|
|
90
|
+
There are three kinds:
|
|
91
|
+
|
|
92
|
+
- **Local**, `createLocalRootSigner`, signs with the root key itself.
|
|
93
|
+
`subject` defaults to the whole account and `policy` to none.
|
|
94
|
+
- **Grant**, `grantSigner`, is what an app uses. It returns the one note the
|
|
95
|
+
account home gave the app, and refuses once the grant has expired. It can't
|
|
96
|
+
make new notes.
|
|
97
|
+
- **Across a port**, `serveSigner` on the side with the key and
|
|
98
|
+
`remoteSigner` on the node's side, as a page signs for its worker. It signs
|
|
99
|
+
only session notes (command `/`, no subject, no policy) and refuses anything
|
|
100
|
+
else without asking the signer behind it.
|
|
101
|
+
|
|
102
|
+
### The session note
|
|
103
|
+
|
|
104
|
+
This is the note a node asks for when it starts:
|
|
103
105
|
|
|
104
106
|
```
|
|
105
107
|
aud = session DID
|
|
106
108
|
sub = the account's DID
|
|
107
|
-
cmd = "/" (
|
|
109
|
+
cmd = "/" (an agent's node signs under its grant, `/record`)
|
|
108
110
|
pol = []
|
|
109
111
|
exp = now + sessionTtlSeconds (default 3600)
|
|
110
|
-
nbf = now − 300
|
|
112
|
+
nbf = now − 300
|
|
111
113
|
```
|
|
112
114
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
([spec 06 §1.2](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
|
|
116
|
-
|
|
117
|
-
**Issuing.** `issueDelegation` defaults `exp` to now + 3600, `nbf` to now − 300
|
|
118
|
-
(`UCAN_CLOCK_SKEW_SECONDS`, so a peer whose clock is a little behind still
|
|
119
|
-
accepts it), `nonce` to 12 random bytes in base64url, `subject` to the
|
|
120
|
-
issuer's own DID and `policy` to `[]`; it signs in the low-S form only.
|
|
121
|
-
Only the account's root signer issues notes peers accept: a note is one
|
|
122
|
-
token from the account, never passed on
|
|
123
|
-
([spec 01 §7.5](https://github.com/leifriksheim/minca/blob/main/spec/01-identity.md)).
|
|
124
|
-
A key that needs another key (a helper, a key per tab) asks the account,
|
|
125
|
-
through its home or root signer, for a note of its own.
|
|
126
|
-
|
|
127
|
-
**What a home grants.** `grantTerms(access, spaces)` (and `noteTerms` under it)
|
|
128
|
-
turns a grant into a note's terms: `/`, `/record` or `/record/read`; the
|
|
129
|
-
whole account, or one space as the subject, or several named by a policy on
|
|
130
|
-
`.space`; none, as a policy nothing satisfies. `noteSpaces(note)` reads that
|
|
131
|
-
back, for showing which spaces a note reaches, and reaches no space for a
|
|
132
|
-
policy statement it can't read that way, so it never offers more than the
|
|
133
|
-
note grants; peers judge each use against the note itself
|
|
134
|
-
([spec 06 §2.5](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
|
|
135
|
-
|
|
136
|
-
_Source: `packages/core/src/identity/root-signer.ts`, `packages/core/src/node/remote.ts` (`serveSigner`, `remoteSigner`), `packages/core/src/identity/ucan.ts` (`issueDelegation`, `verifyNote`), `packages/core/src/identity/abilities.ts` (`noteTerms`, `noteSpaces`), `packages/core/src/node/node.ts` (`SESSION_COMMAND`, `delegate`), `packages/core/src/session/connect.ts` (`grantSigner`, `grantTerms`). Tests: `packages/core/tests/ucan.test.ts`, `packages/core/tests/remote.test.ts` ("the page's signer, from a worker"), `packages/core/tests/node.test.ts`, `packages/core/tests/connect.test.ts`._
|
|
115
|
+
Peers only check that the note grants what each record needs, so the command
|
|
116
|
+
is the node's choice.
|
|
137
117
|
|
|
138
|
-
|
|
118
|
+
### Issuing notes
|
|
139
119
|
|
|
140
|
-
|
|
141
|
-
|
|
120
|
+
`issueDelegation` defaults `exp` to an hour from now, `nbf` to five minutes
|
|
121
|
+
ago so a peer with a slow clock still accepts it, `nonce` to 12 random bytes,
|
|
122
|
+
`subject` to the issuer and `policy` to `[]`. It signs in low-S form only.
|
|
142
123
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
- If the signer refuses or cannot be reached, the node keeps the note it has
|
|
147
|
-
and asks again after `min(60, ttl / 4)` seconds, repeating until it succeeds
|
|
148
|
-
or the node closes. Once the held note expires, live checks (knocks, live
|
|
149
|
-
messages, connecting to peers) refuse it; records it signs are judged with
|
|
150
|
-
no time, so they count until its key is revoked.
|
|
124
|
+
Only the account's root signer issues notes that peers accept, and a note is
|
|
125
|
+
never passed on. A key that needs another key, such as a helper or a key per
|
|
126
|
+
tab, asks the account for a note of its own.
|
|
151
127
|
|
|
152
|
-
|
|
153
|
-
`delegate` call with the one note an account home granted, unchanged, and
|
|
154
|
-
refuses once `grant.expiresAt` has passed. `grantSigner(() => grant)` answers
|
|
155
|
-
with whichever grant the getter returns, as the desktop app's node does when
|
|
156
|
-
a renewed grant replaces the last. A node started from a grant
|
|
157
|
-
therefore never gets a fresh note: its "renewal" returns the same note, and when
|
|
158
|
-
it runs out the app must connect again ([spec 06 §2.9](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
|
|
128
|
+
### What a home grants
|
|
159
129
|
|
|
160
|
-
`
|
|
130
|
+
`grantTerms(access, spaces)` turns a grant into a note's terms: the command
|
|
131
|
+
`/`, `/record` or `/record/read`, and the whole account, one space, or several
|
|
132
|
+
spaces named by a policy. `noteSpaces(note)` reads that back, to show which
|
|
133
|
+
spaces a note reaches. It never claims more than the note grants.
|
|
134
|
+
[Spec 01 §7](https://github.com/leifriksheim/minca/blob/main/spec/01-identity.md),
|
|
135
|
+
[spec 06 §2.5](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md).
|
|
161
136
|
|
|
162
|
-
|
|
137
|
+
## Renewing the session note
|
|
163
138
|
|
|
164
|
-
|
|
139
|
+
The node asks for a new note three quarters of the way through the old one:
|
|
140
|
+
2700 seconds in, with the default lifetime. Each renewal schedules the next.
|
|
165
141
|
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
| `registry` | the node's list of spaces and their keys | yes: the node asks for `{ seal: true }` |
|
|
171
|
-
| `spaces/<spaceId>` | one space's records and what the node keeps about it | no |
|
|
172
|
-
| `writers` | the last place each lasting key took in each line | no |
|
|
173
|
-
|
|
174
|
-
What a path means is the factory's choice:
|
|
175
|
-
|
|
176
|
-
- `indexedDBStores(prefix)` — one IndexedDB database per path, named
|
|
177
|
-
`<prefix>:<path with / replaced by :>`. Never sealed: the browser profile
|
|
178
|
-
already guards it.
|
|
179
|
-
- `folderStores(directory, { basePath?, localKey?, local? })` — a data folder
|
|
180
|
-
([sync and storage](storage.md#data-folders)): the `registry` in the folder
|
|
181
|
-
under `basePath`, sealed under `localKey` (`deriveLocalKey(seed)`) when one
|
|
182
|
-
is given; every other path in `local`; and each space mirrored to the
|
|
183
|
-
folder's segments, which the factory names as `folder`.
|
|
184
|
-
- `directoryStores(directory, { localKey? })` — a directory on this device,
|
|
185
|
-
one file per entry and per version; the `registry` sealed as above.
|
|
186
|
-
|
|
187
|
-
Every version a node signs in a space takes the next place in its key's line
|
|
188
|
-
for that collection there ([spec 02 §4.10](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)).
|
|
189
|
-
Writes by one key in one space go one at a time, and the place is remembered
|
|
190
|
-
before the version leaves the node. Where the places are kept depends on the key:
|
|
191
|
-
|
|
192
|
-
- **A key made for this run** lives only as long as the node, so its places
|
|
193
|
-
are kept in memory.
|
|
194
|
-
- **A claimed writer key** (`config.writerKey`) keeps them in its slot, beside
|
|
195
|
-
the key.
|
|
196
|
-
- **A key handed in** (`config.sessionKey`, an agent's) or a carrier's own key
|
|
197
|
-
keeps them in the `writers` store, and a restart carries on where it left off.
|
|
198
|
-
Such a key may be signing in several nodes at once: every tab of an app
|
|
199
|
-
signs with the app's key. So each place is taken under a Web Lock
|
|
200
|
-
(`minca-writer:lines/<did>/<space>`) every tab and worker of the origin
|
|
201
|
-
shares, and read afresh from the store inside it, never from a copy in
|
|
202
|
-
memory. Nodes that share a key must share that store too, as tabs of one
|
|
203
|
-
origin share IndexedDB; two nodes signing with one key from separate stores,
|
|
204
|
-
or in separate processes without a shared lock, fork its lines, and every
|
|
205
|
-
peer then withdraws what it signed in a forked collection from the fork on.
|
|
206
|
-
|
|
207
|
-
_Source: `packages/core/src/node/writers.ts` (`createWriters`, `exclusively`). Tests: `packages/core/tests/writer-logs.test.ts` ("a writer’s log", "two nodes sharing a handed-in key…")._
|
|
142
|
+
If the signer refuses or can't be reached, the node keeps its note and asks
|
|
143
|
+
again after `min(60, ttl / 4)` seconds, until it succeeds or the node closes.
|
|
144
|
+
Once the note expires, live checks refuse it: knocks, live messages and
|
|
145
|
+
connecting to peers. Records it signed still count until its key is revoked.
|
|
208
146
|
|
|
209
|
-
|
|
147
|
+
A node started from a grant never gets a fresh note. `grantSigner(grant)`
|
|
148
|
+
answers every renewal with the same note, and when that runs out the app must
|
|
149
|
+
connect again. `grantSigner(() => grant)` answers with whatever grant the
|
|
150
|
+
getter returns, so a renewed grant can replace the last.
|
|
151
|
+
|
|
152
|
+
`node.delegation()` returns the note the node writes under now.
|
|
153
|
+
[Spec 06 §1.2](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md).
|
|
210
154
|
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
and withdraw what the key wrote. A slot whose connection the browser
|
|
241
|
-
closed opens again only while it still holds the key.
|
|
242
|
-
- The CLI keeps them outside its home, in `<local>/writer-keys/slot-<n>/` (`localPath` in `packages/cli/src/home.ts`, [sync and storage](storage.md#data-folders)): the key as
|
|
243
|
-
JWK in an envelope (spec 01 §9.1) under the account's local key, with label
|
|
244
|
-
`minca/writer-key/v1` and bound `{ did: <account DID>, slot: <n> }`
|
|
245
|
-
(`key.sealed`, mode 600), so a copy of the files can't sign, and a key file
|
|
246
|
-
moved to another slot or account is refused rather than used; its places in
|
|
247
|
-
`heads/`; and numbered `lock.<n>` files naming the process that holds the
|
|
248
|
-
highest, taken over once that process is gone.
|
|
249
|
-
|
|
250
|
-
_Source: `packages/core/src/node/writer-keys.ts` (`browserWriterKeys`), `packages/core/src/node/writers.ts` (`createWriters`), `packages/core/src/node/node.ts` (`createNode`, `revokeSelf`), `packages/core/src/node/stores.ts` (`writerKeysFor`), `packages/core/src/node/worker.ts` (`withWriterKey`), `packages/cli/src/writer-keys.ts` (`fileWriterKeys`), `packages/cli/src/home.ts` (`unlock`, `nodeFor`). Tests: `packages/core/tests/writer-logs.test.ts` ("a writer key that outlives the node"), `packages/cli/tests/writer-keys.test.ts` ("a key file moved to another slot, or to another account, does not open")._
|
|
251
|
-
|
|
252
|
-
Sign-in ([sign-in](sign-in.md)) uses `storesFor(account)`: IndexedDB with prefix
|
|
253
|
-
`minca:<dataPath with : for />` in the browser, or `folderStores(pod,
|
|
155
|
+
## Stores
|
|
156
|
+
|
|
157
|
+
A node asks its `StoreFactory` for stores by path:
|
|
158
|
+
|
|
159
|
+
| Path | Holds | Sealed |
|
|
160
|
+
| ------------------ | ----------------------------------------------------- | ------ |
|
|
161
|
+
| `registry` | the node's list of spaces and their keys | yes |
|
|
162
|
+
| `spaces/<spaceId>` | one space's records, and what the node keeps about it | no |
|
|
163
|
+
| `writers` | each lasting key's place in each line | no |
|
|
164
|
+
|
|
165
|
+
It also opens `mirrors/<spaceId>/<n>` for a [mirror](storage.md#mirrors),
|
|
166
|
+
`folder/<spaceId>` for a data folder, and `host` for a host's subscriptions.
|
|
167
|
+
|
|
168
|
+
What a path means is up to the factory:
|
|
169
|
+
|
|
170
|
+
- `indexedDBStores(prefix)` makes one IndexedDB database per path, named
|
|
171
|
+
`<prefix>:<path with / replaced by :>`. It never seals, since the browser
|
|
172
|
+
profile already guards it.
|
|
173
|
+
- `folderStores(directory, { basePath?, localKey?, local? })` uses a
|
|
174
|
+
[data folder](storage.md#data-folders). The `registry` goes in the folder
|
|
175
|
+
under `basePath`, sealed under `localKey` (`deriveLocalKey(seed)`) when
|
|
176
|
+
given. Every other path goes in `local`, and each space is mirrored to the
|
|
177
|
+
folder's segments.
|
|
178
|
+
- `directoryStores(directory, { localKey? })` uses a directory on this
|
|
179
|
+
device, one file per entry and per version, sealing the `registry` the same
|
|
180
|
+
way.
|
|
181
|
+
|
|
182
|
+
[Sign-in](sign-in.md) picks stores with `storesFor(account)`: IndexedDB with
|
|
183
|
+
prefix `minca:<dataPath with : for />` in the browser, or `folderStores(pod,
|
|
254
184
|
{ basePath: account.dataPath, localKey })` in a pod, where `dataPath` is
|
|
255
|
-
`accounts/<id>/stores`. A connected app uses
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
[05](https://github.com/leifriksheim/minca/blob/main/spec/05-sync-and-storage.md).
|
|
259
|
-
A node also opens `mirrors/<spaceId>/<n>` for a mirror's writer state
|
|
260
|
-
([mirrors](storage.md#mirrors)), `folder/<spaceId>` for a data folder's, and
|
|
261
|
-
a host `host` for its subscriptions.
|
|
185
|
+
`accounts/<id>/stores`. A connected app uses
|
|
186
|
+
`indexedDBStores('minca-app:<account DID>')`. These names may change
|
|
187
|
+
([sync and storage](storage.md#indexeddb)). A pod's layout is in
|
|
188
|
+
[spec 05](https://github.com/leifriksheim/minca/blob/main/spec/05-sync-and-storage.md).
|
|
262
189
|
|
|
263
|
-
|
|
264
|
-
account holds, with its key and records, from one set of stores to another —
|
|
265
|
-
the account registry too, when `accountKey` is given. It is a union: every
|
|
266
|
-
version goes through the same ordering rule as sync, so copying into a store
|
|
267
|
-
that holds some of it already is safe, and copying twice changes nothing.
|
|
190
|
+
### Copying an account
|
|
268
191
|
|
|
269
|
-
|
|
270
|
-
|
|
192
|
+
`copyAccountData({ from, to, did, accountKey? })` copies every space an
|
|
193
|
+
account holds, with its keys and records, from one set of stores to another.
|
|
194
|
+
With `accountKey` it copies the account registry too. It merges by the same
|
|
195
|
+
rule as sync, so copying into a store that has some of it already is safe,
|
|
196
|
+
and copying twice changes nothing.
|
|
197
|
+
|
|
198
|
+
> **Known defect:** `copyAccountData` stores versions without validating
|
|
199
|
+
> them, so a pod another origin wrote to can
|
|
200
|
+
> bring in versions a peer's would have been refused. Tracked in
|
|
201
|
+
> [#20](https://github.com/leifriksheim/minca/issues/20).
|
|
202
|
+
|
|
203
|
+
### Places in a key's line
|
|
204
|
+
|
|
205
|
+
Every version a key signs in a space takes the next place in that key's line
|
|
206
|
+
for the collection. Writes by one key in one space go one at a time, and the
|
|
207
|
+
place is saved before the version leaves the node. Where it is saved depends
|
|
208
|
+
on the key:
|
|
209
|
+
|
|
210
|
+
- **A key made for this run** keeps its places in memory.
|
|
211
|
+
- **A writer key** (`config.writerKey`) keeps them beside the key.
|
|
212
|
+
- **A key handed in** (`config.sessionKey`) or a carrier's key keeps them in
|
|
213
|
+
the `writers` store, so a restart carries on.
|
|
214
|
+
|
|
215
|
+
A handed-in key may sign in several nodes at once: every tab of an app signs
|
|
216
|
+
with the app's key. So each place is taken under a Web Lock
|
|
217
|
+
(`minca-writer:lines/<did>/<space>`) shared by the origin's tabs and workers,
|
|
218
|
+
and read fresh from the store each time. Nodes that share a key must share
|
|
219
|
+
that store too. Two nodes signing with one key from separate stores fork its
|
|
220
|
+
lines, and every peer then withdraws what it signed in a forked collection
|
|
221
|
+
from the fork on.
|
|
222
|
+
[Spec 02 §4.10](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md).
|
|
271
223
|
|
|
272
|
-
|
|
273
|
-
> `addVersion` directly, without running it through the validation
|
|
274
|
-
> pipeline (`packages/core/src/node/copy.ts`). A pod or data folder that another origin
|
|
275
|
-
> wrote to can bring versions this node would have refused from a peer. A fix
|
|
276
|
-
> will validate on copy, as sync does.
|
|
277
|
-
> Tracked in [#20](https://github.com/leifriksheim/minca/issues/20).
|
|
224
|
+
### Writer keys
|
|
278
225
|
|
|
279
|
-
|
|
226
|
+
With `writerKey`, a node claims a lasting key when it starts and signs with
|
|
227
|
+
it until it closes. The device then keeps one log in each space, instead of
|
|
228
|
+
a new one each run. A key goes to one node at a time. If every key is taken,
|
|
229
|
+
or none can be locked, the node makes a key for this run instead.
|
|
230
|
+
|
|
231
|
+
In the browser, `browserWriterKeys(name)` keeps up to 32 keys in IndexedDB,
|
|
232
|
+
one database per slot (`<name>:writer:<slot>`), each claimed under a Web Lock
|
|
233
|
+
of the same name. A tab that finds a slot taken tries the next. A tab that
|
|
234
|
+
closes or crashes frees its slot. The private key can't be extracted: a
|
|
235
|
+
script in the page can sign with it while it runs, but can't take it away.
|
|
236
|
+
Without IndexedDB or Web Locks there are no writer keys.
|
|
237
|
+
|
|
238
|
+
A node started from a store description, such as `startPageNode` or a node in
|
|
239
|
+
a worker, claims its key under the account's IndexedDB prefix, even when its
|
|
240
|
+
stores are in a data folder. So signing out (`deleteBrowserData`) deletes the
|
|
241
|
+
keys too, and a key never goes in a data folder that other apps share.
|
|
242
|
+
|
|
243
|
+
What happens when a key goes away:
|
|
244
|
+
|
|
245
|
+
- `forget()` drops the key but keeps its places, which still count for this
|
|
246
|
+
run. The slot's next claim makes a new key and clears them.
|
|
247
|
+
- `revokeSelf` forgets the claimed key before it writes a single revoke, so a
|
|
248
|
+
page closed mid-way leaves no revoked key to claim again. With a peer
|
|
249
|
+
connected in any open space, each revoke waits up to `waitMs` for one to
|
|
250
|
+
take it in.
|
|
251
|
+
- A node that claims a key the account registry has revoked forgets it, and
|
|
252
|
+
uses a key for this run. The next start claims a new lasting one.
|
|
253
|
+
- A node never signs at a place behind one it already took this run. If the
|
|
254
|
+
slot lost its places (site data cleared while the page was open), every
|
|
255
|
+
write fails until the page reloads, since signing on would fork the line.
|
|
256
|
+
A slot whose connection the browser closed reopens only while it still
|
|
257
|
+
holds the key.
|
|
258
|
+
|
|
259
|
+
The CLI keeps its writer keys outside its home, in
|
|
260
|
+
`<local>/writer-keys/slot-<n>/` ([data folders](storage.md#data-folders)).
|
|
261
|
+
The key is sealed under the account's local key in `key.sealed` (mode 600,
|
|
262
|
+
label `minca/writer-key/v1`, bound to `{ did, slot }`), so a copy of the files
|
|
263
|
+
can't sign, and a key moved to another slot or account is refused. Its places
|
|
264
|
+
are in `heads/`, and numbered `lock.<n>` files name the process holding it,
|
|
265
|
+
taken over once that process is gone.
|
|
280
266
|
|
|
281
267
|
## Opening and holding spaces
|
|
282
268
|
|
|
283
|
-
A space
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
account manages it ([spec 06 §4.2](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
|
|
269
|
+
A space opens the first time anything asks for it: a read, a write, a status.
|
|
270
|
+
Opening reads its store, joins its peers and starts syncing. It also
|
|
271
|
+
publishes the account's profile there, checks whether the node's note was
|
|
272
|
+
revoked there ([`revoked`](#events)), and names the account's carriers as
|
|
273
|
+
keepers if the account manages the space.
|
|
289
274
|
|
|
290
|
-
|
|
291
|
-
|
|
275
|
+
The space stays open until it is released or the node closes.
|
|
276
|
+
`spaces.hold(id)` keeps it open, and resolves to a function that lets go:
|
|
292
277
|
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
- Reading or writing needs no hold.
|
|
278
|
+
```ts
|
|
279
|
+
const release = await node.spaces.hold(space.id);
|
|
280
|
+
// later
|
|
281
|
+
await release();
|
|
282
|
+
```
|
|
299
283
|
|
|
300
|
-
|
|
301
|
-
|
|
284
|
+
- Holds are counted per space. At zero, the space closes.
|
|
285
|
+
- Releasing twice does nothing.
|
|
286
|
+
- A hold from before the space was left is tied to that time. Releasing it
|
|
287
|
+
later doesn't touch a hold made after rejoining.
|
|
288
|
+
- Reading and writing need no hold.
|
|
302
289
|
|
|
303
|
-
|
|
290
|
+
Anything that needs a space live holds it, such as a screen or a call. That
|
|
291
|
+
way a screen going away never cuts off a call in the same space.
|
|
304
292
|
|
|
305
293
|
## Leaving a space
|
|
306
294
|
|
|
307
|
-
`spaces.leave(id)` first gives up the account's place
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
it leaves anyway.
|
|
321
|
-
- Another device of the account that follows the deleted `sys.joined`, and
|
|
322
|
-
still sees the account holding a place, writes the removal itself, and waits
|
|
323
|
-
the same way.
|
|
324
|
-
- Shared to view, or the only reader left, there is nothing to write and
|
|
295
|
+
`spaces.leave(id)` first gives up the account's place. It writes a
|
|
296
|
+
`sys.remove` naming the account, so the others stop counting it a reader and a
|
|
297
|
+
private space's key changes. Leaving needs no grant. Then it deletes the
|
|
298
|
+
space's `sys.joined` record, closes the space and forgets it with its keys.
|
|
299
|
+
|
|
300
|
+
A founder who leaves is a founder no more, for good. To stay without being
|
|
301
|
+
one, use [`spaces.stepDown`](permissions.md#the-top-and-founders).
|
|
302
|
+
|
|
303
|
+
- The removal waits up to 5 seconds for a peer of another account to have
|
|
304
|
+
it. With nobody reachable, the node leaves anyway.
|
|
305
|
+
- Another device of the account that sees the `sys.joined` record go, while
|
|
306
|
+
the account still holds a place, writes the removal itself.
|
|
307
|
+
- Shared to view, or the last reader left, there's nothing to write, and
|
|
325
308
|
`leave` returns at once.
|
|
326
|
-
- A note that may not change access
|
|
327
|
-
|
|
309
|
+
- A narrow app note that may not change access can't write the removal.
|
|
310
|
+
`leave` still forgets the space, and another device writes it.
|
|
328
311
|
|
|
312
|
+
The account registry, the contacts space and carry spaces can't be left.
|
|
329
313
|
`contacts.remove` and `contacts.block` leave the space for two this way.
|
|
330
|
-
|
|
331
|
-
_Source: `packages/core/src/node/node.ts` (`spaces.leave`, `giveUpPlace`, `forget`, `LEAVE_WAIT_MS`), `packages/core/src/node/space-membership.ts` (`giveUpPlace`), `packages/core/src/node/space-peers.ts` (`writeUntilStored`). Tests: `packages/core/tests/key-change.test.ts` ("leaving a private space"), `packages/core/tests/contacts.test.ts` ("removing a contact gives up your place"), `packages/core/tests/node.test.ts` ("the account registry"), `packages/core/tests/carrier.test.ts` ("its carry space cannot be left…")._
|
|
314
|
+
[Spec 03 §6.2](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md).
|
|
332
315
|
|
|
333
316
|
## Holding part of a space
|
|
334
317
|
|
|
335
|
-
With `config.cache`,
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
318
|
+
A node doesn't need every record in a space. With `config.cache`, once a space
|
|
319
|
+
names at least one keeper, the node holds only the collections it uses, plus
|
|
320
|
+
the space's own `sys.*` collections. Apps connected to an account home do this
|
|
321
|
+
by default.
|
|
322
|
+
|
|
323
|
+
```ts
|
|
324
|
+
declare const signer: RootSigner;
|
|
325
|
+
// ---cut---
|
|
326
|
+
import { createNode, indexedDBStores, type RootSigner } from '@minca/core';
|
|
327
|
+
|
|
328
|
+
const node = await createNode({
|
|
329
|
+
signer,
|
|
330
|
+
stores: indexedDBStores('my-app'),
|
|
331
|
+
cache: { collections: ['app.todo.item'] },
|
|
332
|
+
});
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
`cache` is a [`CacheConfig`](https://minca.dev/api/core/interfaces/CacheConfig/): the
|
|
336
|
+
collections to hold from the start, when to drop one nothing uses, and how
|
|
337
|
+
many keepers a write must reach.
|
|
338
|
+
|
|
339
|
+
### What gets held
|
|
340
|
+
|
|
341
|
+
- A query marks every collection it reads as used, including each
|
|
342
|
+
`include … from`, and a write marks the one it writes. Sync then fetches
|
|
343
|
+
them.
|
|
344
|
+
- Until the node has caught up once with a node holding the whole space, it
|
|
345
|
+
can't know whether the space names keepers, so it holds only what it uses.
|
|
346
|
+
- An unused collection is dropped when the space opens, and every 6 hours
|
|
347
|
+
while it stays open. It stops being held before its versions go, so nothing
|
|
348
|
+
syncs it back meanwhile. A collection with a pending write is never dropped.
|
|
349
|
+
- A space that names no keeper is held whole.
|
|
350
|
+
- The account registry, the contacts space and carry spaces are always held
|
|
351
|
+
whole.
|
|
352
|
+
- When what it holds changes, the node says hello to every peer again.
|
|
353
|
+
|
|
354
|
+
### Complete results
|
|
355
|
+
|
|
356
|
+
A query's result has `complete: false` until, for every collection it reads,
|
|
357
|
+
the node has been level once with a node holding the whole space, and it
|
|
358
|
+
lacks nothing a writer's line there names. A version that names one the node
|
|
359
|
+
doesn't have adds it to `missing`, and the node asks every peer for it by id.
|
|
360
|
+
It asks again whenever the collection is level with a peer.
|
|
361
|
+
|
|
362
|
+
So what a keeper withholds from the middle of a writer's line shows up as
|
|
363
|
+
missing. A writer's newest versions aren't named by any line yet, so holding
|
|
364
|
+
those back would take every peer the node syncs with.
|
|
365
|
+
|
|
366
|
+
### Pending writes
|
|
367
|
+
|
|
368
|
+
In a space that names keepers, every node's own writes are _pending_ until
|
|
369
|
+
`min(keepers named, max(copies ?? 2, cache.copies ?? 0))` keepers have them. A
|
|
370
|
+
keeper's own node counts as one. A keeper confirms a write with `stored`, or by
|
|
371
|
+
being level with the writer on its collection. Only peers named in
|
|
372
|
+
`sys.keepers` count. A node holding part of a space keeps pending writes in
|
|
373
|
+
its store across runs. One holding all of it keeps the latest 4096 in memory.
|
|
374
|
+
|
|
375
|
+
`node.spaces.kept(spaceId, waitMs, since?)` waits up to `waitMs`, at most a
|
|
376
|
+
minute, for this node's writes to be kept elsewhere:
|
|
377
|
+
|
|
378
|
+
- In a space with keepers, it says `'keepers'` once none of its writes from
|
|
379
|
+
`since` (ms) on is pending.
|
|
380
|
+
- In a space without, it says `'peer'` once a connected peer holds all this
|
|
381
|
+
node does. That's less sure, since the peer may be a device that goes away.
|
|
382
|
+
- It says `null` if nobody had them in time.
|
|
383
|
+
|
|
384
|
+
Wait on it before a node stops: a tab about to close, a command about to exit,
|
|
385
|
+
a server's node at the end of its job.
|
|
386
|
+
|
|
387
|
+
### What the node stores
|
|
388
|
+
|
|
389
|
+
This state lives in the space's own store, `spaces/<spaceId>`:
|
|
390
|
+
|
|
391
|
+
| Key | Value (JSON) |
|
|
392
|
+
| ---------------------- | -------------------------------------------------------------------- |
|
|
393
|
+
| `cache` | `{ settled, used, level, missing }`, below |
|
|
394
|
+
| `pending/<version id>` | `{ collection, by: [keeper DID…], at }`, deleted once `by` is enough |
|
|
395
|
+
|
|
396
|
+
In `cache`, `settled` says whether the node has synced with a whole-space
|
|
397
|
+
peer. `used` maps each collection to when a query last used it, `level` to
|
|
398
|
+
when it was first level with a whole-space peer, and `missing` to the version
|
|
399
|
+
ids a writer's line names that aren't here.
|
|
400
|
+
[Spec 05 §9](https://github.com/leifriksheim/minca/blob/main/spec/05-sync-and-storage.md).
|
|
399
401
|
|
|
400
402
|
### Planned: caches that widen and trim
|
|
401
403
|
|
|
402
|
-
> **Planned.**
|
|
403
|
-
>
|
|
404
|
-
>
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
others go missing). Opt-in only (`cache.widen: true`), since done on its own
|
|
409
|
-
it could fill a disk at a bad moment. Open: what "too few" is, and for how
|
|
410
|
-
long. Today a cache only widens as queries use collections.
|
|
411
|
-
- **Trimming by size.** `cache.maxBytes`: above it, drop least recently used
|
|
412
|
-
collections first, undeclared ones before declared. Also trim when
|
|
413
|
-
`navigator.storage.estimate()` says room is low, before the browser clears
|
|
414
|
-
the site. Pending writes are never dropped.
|
|
404
|
+
> **Planned.** A node holding part of a space would hold all of it when too
|
|
405
|
+
> few keepers are online (opt-in, `cache.widen: true`), and drop least
|
|
406
|
+
> recently used collections above `cache.maxBytes` or when the browser runs
|
|
407
|
+
> low on room. Fetching linked records by key, and holding less than a
|
|
408
|
+
> collection, are planned in
|
|
409
|
+
> [spec 05 §9.1](https://github.com/leifriksheim/minca/blob/main/spec/05-sync-and-storage.md).
|
|
415
410
|
|
|
416
411
|
## Following the account
|
|
417
412
|
|
|
418
|
-
|
|
419
|
-
account
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
The node's `registry` store
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
|
432
|
-
|
|
|
433
|
-
| The
|
|
434
|
-
|
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
1. joins every space a
|
|
442
|
-
|
|
443
|
-
2. leaves every space whose `sys.joined` record
|
|
444
|
-
3. writes a `sys.joined` record for
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
and
|
|
459
|
-
account
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
`joining: true` and the node tries again each time records arrive in it.
|
|
473
|
-
|
|
474
|
-
**Leaving.** `spaces.leave(id)` gives up the account's place in the space,
|
|
475
|
-
then deletes the `sys.joined` record, closes the space and forgets it with its
|
|
476
|
-
key ([leaving a space](#leaving-a-space)).
|
|
477
|
-
|
|
478
|
-
_Source: `packages/core/src/node/node.ts` (`reconcileOnce`, `remember`, `forget`, `finishJoining`, `spaces`), `packages/core/src/node/node-contacts.ts` (`publishProfile`), `packages/core/src/space/space-manager.ts`. Tests: `packages/core/tests/node.test.ts` ("the account registry"), `packages/core/tests/profiles.test.ts`, `packages/core/tests/space-access.test.ts`._
|
|
413
|
+
With the account key, a node keeps its spaces in step with the account's
|
|
414
|
+
list in the account registry. Join a space on your phone, and your laptop
|
|
415
|
+
joins it too.
|
|
416
|
+
|
|
417
|
+
The node's own `registry` store lists each space it holds: its keys, an
|
|
418
|
+
invite secret while one waits to be used, the account's place there as last
|
|
419
|
+
seen, the relays the space names, and, for an app without the account key,
|
|
420
|
+
its member key.
|
|
421
|
+
|
|
422
|
+
Three kinds of space are the account's own machinery, and `spaces.list`
|
|
423
|
+
hides them:
|
|
424
|
+
|
|
425
|
+
| Space | Derived from | Notes |
|
|
426
|
+
| -------------------- | ------------------------------------------ | ---------------------------------------------------------------------- |
|
|
427
|
+
| The account registry | the account key | Opened directly. Can't be left. |
|
|
428
|
+
| The contacts space | the account key, or `config.contactsSpace` | In the node's registry, so it can be granted to an app. Can't be left. |
|
|
429
|
+
| Carry spaces | the account key and the carrier's key | Opened directly. Can't be left. |
|
|
430
|
+
|
|
431
|
+
### Reconciling
|
|
432
|
+
|
|
433
|
+
At start, and whenever the account registry changes, the node reconciles,
|
|
434
|
+
one run at a time:
|
|
435
|
+
|
|
436
|
+
1. It joins every space a `sys.joined` record names that it doesn't hold,
|
|
437
|
+
with the view-only invite in the record.
|
|
438
|
+
2. It leaves every space whose `sys.joined` record was deleted.
|
|
439
|
+
3. It writes a `sys.joined` record for a space it holds that the registry
|
|
440
|
+
doesn't know.
|
|
441
|
+
4. It brings every carrier's passes and wakes up to date.
|
|
442
|
+
5. It names the account's carriers as keepers of the open spaces it manages.
|
|
443
|
+
6. It asks each host the account uses how it stands, without waiting, and
|
|
444
|
+
hands it the spaces if it was paid ([hosting](#carriers-hosting-and-notifications)).
|
|
445
|
+
|
|
446
|
+
Creating or joining a space writes its `sys.joined` record. Leaving deletes it.
|
|
447
|
+
|
|
448
|
+
### Profiles
|
|
449
|
+
|
|
450
|
+
The node publishes the account's profile, `{ name, contactKey? }`, in a space
|
|
451
|
+
when it opens, when the account takes a place there, and when the name
|
|
452
|
+
changes on any device. The name comes from the registry's `sys.profile`
|
|
453
|
+
record, and `contactKey` is included only when the node holds it. It skips
|
|
454
|
+
the account registry and the contacts space, an account with no name, and
|
|
455
|
+
any note without `/account/write`, such as an agent's.
|
|
456
|
+
|
|
457
|
+
### Joining
|
|
458
|
+
|
|
459
|
+
`spaces.join(invite)` takes a bare invite, or any link with `#invite=…`,
|
|
460
|
+
`?invite=…` or `&invite=…`. A short link is fetched from its mailboxes first
|
|
461
|
+
([invites](spaces.md#invites)). It stores the space and its key, and
|
|
462
|
+
`memberKey` when given, writes the `sys.joined` record, then uses the
|
|
463
|
+
invite's role secret. If the space's invite record hasn't arrived yet, the
|
|
464
|
+
space shows `joining: true`, and the node tries again each time records
|
|
465
|
+
arrive.
|
|
466
|
+
[Spec 06 §1.3](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md).
|
|
479
467
|
|
|
480
468
|
## Events
|
|
481
469
|
|
|
482
|
-
`node.subscribe(listener)`
|
|
483
|
-
|
|
470
|
+
`node.subscribe(listener)` tells you what happens, and returns a function to
|
|
471
|
+
stop. A listener that throws doesn't stop the others.
|
|
484
472
|
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
473
|
+
```ts
|
|
474
|
+
const stop = node.subscribe((event) => {
|
|
475
|
+
if (event.type === 'records') console.log('changed in', event.space);
|
|
476
|
+
});
|
|
477
|
+
```
|
|
478
|
+
|
|
479
|
+
Each event is a [`NodeEvent`](https://minca.dev/api/core/type-aliases/NodeEvent/), told
|
|
480
|
+
apart by its `type`: records changed, status, the list of spaces, the account,
|
|
481
|
+
a refused version, a live message, a revoked note, or the network.
|
|
494
482
|
|
|
495
|
-
|
|
483
|
+
A `status` change in the account registry is sent for every open space too,
|
|
484
|
+
since that is where the node learns which peers are the account's own.
|
|
496
485
|
|
|
497
486
|
### Versions that wait or are refused
|
|
498
487
|
|
|
499
|
-
A version from a peer stands, waits or is refused
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
- A version
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
peer again. Never by id alone: a copy with a mangled signature has the
|
|
520
|
-
genuine version's id.
|
|
521
|
-
|
|
522
|
-
_Source: `packages/core/src/sync/sync-engine.ts` (`admit`, `admitAll`, `rank`, `MAX_WAITING`, `MAX_REFUSED`). Tests: `packages/core/tests/reconcile.test.ts` ("a refused version is not asked for again", "a version that waits for its first version asks for it at once, and is acknowledged once in")._
|
|
488
|
+
A version from a peer stands, waits or is refused. What the node does with
|
|
489
|
+
each:
|
|
490
|
+
|
|
491
|
+
- A batch is taken in `sys.collection` versions first, then by `seq`, so
|
|
492
|
+
what others depend on is in first and little has to wait.
|
|
493
|
+
- A version that waits is held in memory, at most 1,000, oldest dropped
|
|
494
|
+
first, and judged again whenever something new is stored. One waiting for
|
|
495
|
+
an earlier version asks the peer for it at once.
|
|
496
|
+
- A withdrawn version, allowed when written but taken away by a removal or a
|
|
497
|
+
revoke it hadn't seen, is stored and passed on. It sends no `rejected`
|
|
498
|
+
event and never shows as a record. It is kept for proofs that cite it
|
|
499
|
+
([spec 09 §6](https://github.com/leifriksheim/minca/blob/main/spec/09-contracts.md)).
|
|
500
|
+
- A version that breaks its collection's [contract](contracts.md) is also
|
|
501
|
+
stored and passed on, with no `rejected` event, and `records.get` and
|
|
502
|
+
queries skip it.
|
|
503
|
+
- A refused version sends a `rejected` event and is remembered by peer and
|
|
504
|
+
id, at most 10,000, so it isn't asked of that peer again. Never by id
|
|
505
|
+
alone: a copy with a mangled signature has the real version's id.
|
|
506
|
+
|
|
507
|
+
[Spec 02 §9.5](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md).
|
|
523
508
|
|
|
524
509
|
## Live messages and status
|
|
525
510
|
|
|
526
|
-
`spaces.send(id, message, to?)` sends
|
|
527
|
-
the space right now
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
> Rationale: a peer's key does not say whose it is, but only the account's own
|
|
567
|
-
> devices and apps can read its registry, so a peer there is one of ours.
|
|
568
|
-
|
|
569
|
-
_Source: `packages/core/src/node/node.ts` (`spaces.send`, `spaces.status`), `packages/core/src/node/space-peers.ts` (`send`, `onLive`), `packages/core/src/node/space-runtime.ts` (`status`). Tests: `packages/core/tests/live.test.ts`._
|
|
511
|
+
`spaces.send(id, message, to?)` sends any JSON value to the peers connected
|
|
512
|
+
in the space right now. It isn't stored or signed. Use it for things like
|
|
513
|
+
"typing…" or a cursor.
|
|
514
|
+
|
|
515
|
+
```ts
|
|
516
|
+
await node.spaces.send(space.id, { typing: true });
|
|
517
|
+
```
|
|
518
|
+
|
|
519
|
+
- The message, as JSON, can be at most 65,536 characters. Longer throws
|
|
520
|
+
"A live message can be at most 64 KB".
|
|
521
|
+
- It goes once to each connected peer, over whichever network it last used.
|
|
522
|
+
- With `to`, it goes only to the peer with that session DID (one device), or
|
|
523
|
+
to every device of the account with that DID. A peer whose account isn't
|
|
524
|
+
checked yet is matched by session DID only.
|
|
525
|
+
- In a private space, nothing goes to someone removed or who left, and
|
|
526
|
+
nothing from them arrives.
|
|
527
|
+
- An agent's node refuses `send`.
|
|
528
|
+
|
|
529
|
+
Each peer may send a burst of 60, then 20 a second.
|
|
530
|
+
|
|
531
|
+
A message that arrives is a `message` [event](https://minca.dev/api/core/type-aliases/NodeEvent/),
|
|
532
|
+
with the value sent, the sender's account and the device it came from.
|
|
533
|
+
|
|
534
|
+
[Spec 04 §9](https://github.com/leifriksheim/minca/blob/main/spec/04-network.md).
|
|
535
|
+
|
|
536
|
+
### Status
|
|
537
|
+
|
|
538
|
+
`spaces.status(id)` tells you how a space is connected, as a
|
|
539
|
+
[`SpaceStatus`](https://minca.dev/api/core/interfaces/SpaceStatus/): its connection, the peers
|
|
540
|
+
connected and whose they are, a fingerprint of what it holds, and what it
|
|
541
|
+
holds and still has pending.
|
|
542
|
+
|
|
543
|
+
`connection` is `offline` with no network, and `connected` while any one
|
|
544
|
+
relay socket or peer is. A space whose relays all drop and whose peers leave
|
|
545
|
+
goes back to `connecting`. It is `error` only when the first connect failed
|
|
546
|
+
and nothing has connected since.
|
|
547
|
+
|
|
548
|
+
A peer's key doesn't say whose it is. But only the account's own devices and
|
|
549
|
+
apps can read its registry, so a peer there is one of ours. That is how `own`
|
|
550
|
+
is worked out.
|
|
570
551
|
|
|
571
552
|
## The rest of the node's surface
|
|
572
553
|
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
to
|
|
624
|
-
|
|
625
|
-
for
|
|
626
|
-
|
|
627
|
-
- `
|
|
628
|
-
|
|
629
|
-
|
|
554
|
+
Every value a node method returns can be turned into JSON. So the same calls
|
|
555
|
+
work over a command line, MCP and WebMCP ([actions](actions.md)).
|
|
556
|
+
|
|
557
|
+
### Spaces
|
|
558
|
+
|
|
559
|
+
`node.spaces` creates, invites, previews, joins and leaves spaces, and
|
|
560
|
+
manages who is in them: `access`, `may`, `holdsRole`, `defineRole`, `assign`,
|
|
561
|
+
`unassign`, `removeMember`, `stepDown`, `succeed`, `closeInvite`,
|
|
562
|
+
`changeKey`, `setRelays`, `setKeepers`, `revoke`, `profiles` and
|
|
563
|
+
`authenticator` ([spaces](spaces.md)).
|
|
564
|
+
|
|
565
|
+
An invite is for `member` when the inviter may give that role. Otherwise it's
|
|
566
|
+
for the first role by name the inviter may give, or view-only with none
|
|
567
|
+
([invites](spaces.md#invites)).
|
|
568
|
+
|
|
569
|
+
- `access(id)` gives a [`SpaceAccess`](https://minca.dev/api/core/interfaces/SpaceAccess/):
|
|
570
|
+
the roles with their current definitions, the members, invites, founders,
|
|
571
|
+
successors, keepers and more
|
|
572
|
+
([the top and founders](permissions.md#the-top-and-founders)).
|
|
573
|
+
- `may(id, cmd, args?, account?)` asks whether an account may run a command
|
|
574
|
+
with these arguments now. Apps use it to show what someone can do. Peers
|
|
575
|
+
still judge each version on its own.
|
|
576
|
+
- `holdsRole(id, role, account?)` asks whether an account holds every grant a
|
|
577
|
+
role gives, each as wide or wider. It compares the words only, so it may
|
|
578
|
+
say no where the policies would allow, but never yes where they wouldn't.
|
|
579
|
+
Apps use it before giving a bot a role.
|
|
580
|
+
- `defineRole(id, { name, title?, grants, nests? })` writes a role. It can
|
|
581
|
+
hold only what this account could do itself.
|
|
582
|
+
- `assign(id, did, role)` and `unassign(id, did, role)` give and take a role.
|
|
583
|
+
Taking your own needs no grant. `removeMember(id, did)` removes an account
|
|
584
|
+
with all its roles, and removing yourself is leaving. Taking power away
|
|
585
|
+
writes a cutoff at what this node holds of theirs.
|
|
586
|
+
|
|
587
|
+
[Spec 03](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md).
|
|
588
|
+
|
|
589
|
+
### Revokes
|
|
590
|
+
|
|
591
|
+
`spaces.revoke(space, key, { waitMs? })` and `account.revoke(key, { waitMs? })`
|
|
592
|
+
resolve once the revoke is written. With `waitMs`, they wait until a peer has
|
|
593
|
+
taken it in or that time has passed, and say `true` when one did. With no
|
|
594
|
+
network, that is `false` at once. A node about to stop should wait like
|
|
595
|
+
this, since it sends nothing afterwards.
|
|
596
|
+
|
|
597
|
+
### Records and the account
|
|
598
|
+
|
|
599
|
+
- `node.records` and `node.collections` read and write records
|
|
600
|
+
([records and queries](records-and-queries.md), [collections](collections.md)).
|
|
601
|
+
`records.watch` runs a query again after each `records` event for its
|
|
602
|
+
space, one run at a time, with at most one more queued.
|
|
603
|
+
- `node.account` needs the account key. `profile()` reads the profile.
|
|
604
|
+
`setName(name)` writes it to the registry, then publishes it in every open
|
|
605
|
+
space. `setAvatar({ bytes, mime } | null, { name? })` and `picture()` do the
|
|
606
|
+
same for the account's picture ([spaces](spaces.md)). `revoke` revokes one
|
|
607
|
+
of the account's keys in the registry.
|
|
608
|
+
- `account.space()` is the registry's id. Keep what is the person's own
|
|
609
|
+
across their devices there, like an app's settings: define a collection of
|
|
610
|
+
yours and write records, as in any space. Every device of the account and
|
|
611
|
+
every app given the whole account reads them. Writing there needs the
|
|
612
|
+
whole account's write access: what an agent writes there counts for
|
|
613
|
+
nothing. Keep it small, settings and not files or lists that grow: every
|
|
614
|
+
device holds the registry whole, and carriers carry it. Leave the `sys.*`
|
|
615
|
+
records alone, and give a collection one definition, shared by every app
|
|
616
|
+
that uses it. An app given only some spaces has no registry: it keeps its
|
|
617
|
+
settings in a space it was given, or on the device.
|
|
618
|
+
- `node.contacts` ([contacts](contacts.md)). `ask` and `accept` make a space
|
|
619
|
+
for two, so they need whole-account access (`/account/write`).
|
|
620
|
+
- `node.direct` ([direct messages](direct-messages.md)): `reachable`, `send`
|
|
621
|
+
and `list`. It needs the account's member key for the space.
|
|
622
|
+
- `node.inbox` ([the inbox](#the-inbox)) needs the contact key. Knocking and
|
|
630
623
|
accepting also need whole-account access.
|
|
631
|
-
- `node.carriers`, `node.hosting
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
624
|
+
- `node.carriers`, `node.hosting` and `node.notifications`
|
|
625
|
+
([carriers and hosting](#carriers-hosting-and-notifications)).
|
|
626
|
+
|
|
627
|
+
### The network and agents
|
|
628
|
+
|
|
629
|
+
- `node.iceServers()` gives the ICE servers for your own connections, such as
|
|
630
|
+
[calls](../../calls/README.md#connections) ([the network](#the-network)).
|
|
631
|
+
- `node.network.status()` shows each relay's state, the connections open and
|
|
632
|
+
being made, and whether a relay offered TURN. `reconnect()` redials a
|
|
633
|
+
waiting relay now. A `network` event follows each change. This is local
|
|
634
|
+
only.
|
|
635
|
+
- `node.asAgent({ keys, note })` ([acting as an agent](#a-node-acting-as-an-agent)).
|
|
642
636
|
|
|
643
637
|
## The network
|
|
644
638
|
|
|
645
|
-
How
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
`
|
|
711
|
-
the
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
639
|
+
How this node uses relays, always-on nodes and WebRTC. Another
|
|
640
|
+
implementation may pick other numbers and still talk to this one
|
|
641
|
+
([spec 04](https://github.com/leifriksheim/minca/blob/main/spec/04-network.md)).
|
|
642
|
+
|
|
643
|
+
### Relays
|
|
644
|
+
|
|
645
|
+
Network settings can mix kinds of relay:
|
|
646
|
+
|
|
647
|
+
```ts
|
|
648
|
+
import type { NodeNetworkConfig } from '@minca/core';
|
|
649
|
+
|
|
650
|
+
const network: NodeNetworkConfig = {
|
|
651
|
+
relays: ['wss://relay.minca.social', 'nostr+wss://relay.damus.io'],
|
|
652
|
+
};
|
|
653
|
+
```
|
|
654
|
+
|
|
655
|
+
A relay of a kind the library doesn't speak is left out of
|
|
656
|
+
`network.status()`. On a Nostr relay, each event is signed with a throwaway
|
|
657
|
+
key.
|
|
658
|
+
|
|
659
|
+
When a relay drops, the node redials after 1, 2, 4, 8 and 16 seconds, then
|
|
660
|
+
every 30, each ±25% so peers that dropped together don't return together. It
|
|
661
|
+
never stops until `disconnect`. It tries at once when the page becomes
|
|
662
|
+
visible, when the browser reports `online`, and on `reconnect()`. A
|
|
663
|
+
successful open resets the count.
|
|
664
|
+
|
|
665
|
+
A socket can die without closing, as it does when the device sleeps. So the
|
|
666
|
+
node checks the clock every 5 seconds, and a gap over 30 seconds means it
|
|
667
|
+
slept: it drops the socket and dials again. A socket to a Minca relay that
|
|
668
|
+
has heard nothing for 30 seconds sends `ping`. Once the relay has answered
|
|
669
|
+
one, two unanswered pings end the socket ("The relay stopped answering.").
|
|
670
|
+
|
|
671
|
+
Each relay's state is a [`RelayStatus`](https://minca.dev/api/core/interfaces/RelayStatus/):
|
|
672
|
+
connecting, open, waiting to try again (with when and why), or stopped.
|
|
673
|
+
|
|
674
|
+
A socket opened only for a space's own relays closes once no space needs it.
|
|
675
|
+
A node that may change a space's relays (`/space/relays`), in a space that
|
|
676
|
+
names none, names its own relays there, up to 8.
|
|
677
|
+
|
|
678
|
+
### Meeting peers
|
|
679
|
+
|
|
680
|
+
A node says hello in each space's room when it joins, on each relay as it
|
|
681
|
+
opens, and every 2 minutes.
|
|
682
|
+
|
|
683
|
+
- It says hello back at most once every 10 seconds, to everyone who said
|
|
684
|
+
hello meanwhile.
|
|
685
|
+
- It remembers, per room, the hellos it acted on from each peer in the last 2
|
|
686
|
+
minutes (up to 256 a peer), and failed tries for the last 512 peers.
|
|
687
|
+
- Each socket sends at most 20 messages a second, in bursts of 40, and queues
|
|
688
|
+
the rest.
|
|
689
|
+
- A connection attempt that times out is tried again at the peer's next
|
|
690
|
+
hello.
|
|
691
|
+
- Each WebRTC offer or answer waits up to 2 seconds for ICE gathering.
|
|
692
|
+
|
|
693
|
+
### Connections
|
|
694
|
+
|
|
695
|
+
- A connection no room takes up within 10 seconds is closed.
|
|
696
|
+
- An attempt gets 20 seconds, doubling with each failure at the same peer, up
|
|
697
|
+
to 5 minutes.
|
|
698
|
+
- The node remembers the last 512 signals it relayed, by their signatures.
|
|
699
|
+
- A node that must prove read access but holds no read key fails the
|
|
700
|
+
handshake, and the room times out.
|
|
701
|
+
|
|
702
|
+
### Always-on nodes
|
|
703
|
+
|
|
704
|
+
`network.nodes` lists nodes to dial, one socket per node per space. After an
|
|
705
|
+
unexpected close the node redials forever, waiting `min(1 s · 2ⁿ, 30 s)`,
|
|
706
|
+
±25%, like a relay. A deliberate close is never redialled. The node's `/peer`
|
|
707
|
+
endpoint waits 10 seconds for the hello.
|
|
708
|
+
|
|
709
|
+
### In-process links
|
|
710
|
+
|
|
711
|
+
`createLocalHub()` links every transport made from it, delivering bytes on a
|
|
712
|
+
later task, copied, as on a real wire. There is no handshake. A carrier uses
|
|
713
|
+
it to keep its copy of a space level with the copy in the person's pod folder.
|
|
714
|
+
|
|
715
|
+
### ICE servers
|
|
716
|
+
|
|
717
|
+
The default ICE servers are STUN only, `stun:stun.l.google.com:19302` and
|
|
718
|
+
`stun:stun1.l.google.com:19302`. `network.iceServers` replaces them. Each new
|
|
719
|
+
WebRTC connection also uses the TURN servers relays offered, while they
|
|
720
|
+
haven't expired.
|
|
721
|
+
|
|
722
|
+
`node.iceServers()` returns the same list, for your own connections. If a
|
|
723
|
+
relay is connected and the TURN passwords are missing or expire within 10
|
|
724
|
+
minutes, it first asks each relay that can, at most once every 10 minutes,
|
|
725
|
+
and waits up to 1.5 seconds. With no relays, it returns the configured
|
|
726
|
+
servers.
|
|
719
727
|
|
|
720
728
|
## A node acting as an agent
|
|
721
729
|
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
730
|
+
An agent writes for a person, but only records, and only where it was let in.
|
|
731
|
+
`node.asAgent({ keys, note })` gives you the same node acting as one:
|
|
732
|
+
|
|
733
|
+
```ts
|
|
734
|
+
import type { Delegation } from '@minca/core';
|
|
735
|
+
declare const keys: CryptoKeyPair;
|
|
736
|
+
declare const note: Delegation;
|
|
737
|
+
// ---cut---
|
|
738
|
+
const agent = await node.asAgent({ keys, note });
|
|
739
|
+
await agent.records.put(space.id, 'app.note', { text: 'Written by the agent' });
|
|
740
|
+
```
|
|
741
|
+
|
|
742
|
+
It throws unless the note verifies, grants records only (under `/record`), is
|
|
743
|
+
made out to `keys`, and was issued by `node.did`. The agent:
|
|
744
|
+
|
|
745
|
+
- signs with its own key under its note, so what it writes is `recordsOnly`;
|
|
746
|
+
- reaches only the spaces its note names, or every space for a note about
|
|
747
|
+
the whole account, and hears no events from others;
|
|
748
|
+
- sees the contact list only if its note covers the contacts space.
|
|
749
|
+
|
|
750
|
+
It refuses everything that needs a person: making, inviting, joining or
|
|
751
|
+
leaving spaces; changing members, roles, invites, revokes, keys, relays or
|
|
752
|
+
keepers; defining or deleting collections; live messages, which a person's
|
|
753
|
+
devices would take as theirs; renaming or revoking at the account level;
|
|
754
|
+
carriers, notifications and hosting; contacts and the inbox; `delegate` and
|
|
755
|
+
`asAgent`.
|
|
756
|
+
|
|
757
|
+
Closing the agent leaves the node running. A node used across a port
|
|
758
|
+
(`remoteNode`) starts no agent, since the agent's keys would have to cross.
|
|
759
|
+
|
|
760
|
+
An agent granted `scope: account` gets a records-only note for every space,
|
|
761
|
+
and the account key, so it can read the contact list. A home never gives a
|
|
762
|
+
records-only key the contact key, which would open the account's knocks
|
|
763
|
+
([the inbox](inbox.md)).
|
|
764
|
+
|
|
765
|
+
One table in the library says which methods an agent passes through, limits
|
|
766
|
+
to its spaces or refuses, and what `remoteNode` forwards. A new method
|
|
767
|
+
doesn't type-check until it's listed there.
|
|
768
|
+
[Spec 06 §2.8](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md).
|
|
753
769
|
|
|
754
770
|
## The app-side client
|
|
755
771
|
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
789
|
-
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
|
|
814
|
-
|
|
815
|
-
|
|
816
|
-
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
|
|
820
|
-
|
|
821
|
-
|
|
822
|
-
|
|
823
|
-
|
|
824
|
-
|
|
825
|
-
|
|
826
|
-
|
|
827
|
-
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
|
|
831
|
-
|
|
832
|
-
|
|
833
|
-
|
|
834
|
-
|
|
835
|
-
|
|
836
|
-
a
|
|
837
|
-
|
|
838
|
-
|
|
839
|
-
|
|
840
|
-
|
|
841
|
-
(`
|
|
842
|
-
|
|
843
|
-
|
|
844
|
-
|
|
845
|
-
|
|
846
|
-
|
|
847
|
-
the
|
|
848
|
-
|
|
849
|
-
|
|
850
|
-
|
|
851
|
-
- `
|
|
772
|
+
An app connects to an account home with `createMincaConnection`
|
|
773
|
+
([building an app](building-an-app.md)). These are the pieces underneath.
|
|
774
|
+
[Spec 06 §2](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)
|
|
775
|
+
says what the app and the home send each other.
|
|
776
|
+
|
|
777
|
+
### The app's key
|
|
778
|
+
|
|
779
|
+
`appKey(name = 'default')` makes the app's P-256 key once and keeps it,
|
|
780
|
+
non-extractable, in the IndexedDB database `minca-app-key`, store `keys`,
|
|
781
|
+
under `name`. `forgetAppKey` deletes it, and the next connection makes a new
|
|
782
|
+
one.
|
|
783
|
+
|
|
784
|
+
### An app's node outside the page
|
|
785
|
+
|
|
786
|
+
The desktop app runs its app's node in a process of its own,
|
|
787
|
+
`minca app-node`, so it keeps running with the window closed. The window
|
|
788
|
+
talks to it over a WebSocket to the shell's server, which opens only for the
|
|
789
|
+
app's window, with a token made for it. One process holds the key, so the
|
|
790
|
+
window and the menu bar share one node. A lock on the folder stops a second
|
|
791
|
+
one, since two nodes signing with one key would fork its lines.
|
|
792
|
+
|
|
793
|
+
Its key and grant rest in its folder as `key.sealed` and `grant.sealed`
|
|
794
|
+
(labels `minca/desktop-app-key/v1` and `minca/desktop-grant/v1`, bound to
|
|
795
|
+
`{ file }`), sealed under a key the shell keeps in the system keychain. Its
|
|
796
|
+
registry is sealed as an account's is. Copied without the keychain, the
|
|
797
|
+
folder gives up no key, grant or private body. A program running as the
|
|
798
|
+
person can still ask the keychain, as it could read a browser profile. A
|
|
799
|
+
folder that doesn't open with the keychain's key is moved aside, and the node
|
|
800
|
+
starts again unconnected.
|
|
801
|
+
|
|
802
|
+
- There's one folder of stores per account. Connecting as another account
|
|
803
|
+
deletes the last one's.
|
|
804
|
+
- Renewing keeps the key. Disconnecting, from the app or the home, forgets it,
|
|
805
|
+
so a revoked key stays revoked.
|
|
806
|
+
- If the home answers as a different account, the app leaves the last one,
|
|
807
|
+
dropping what no peer had taken yet, and asks again with a new key. One key
|
|
808
|
+
never holds two accounts' notes.
|
|
809
|
+
- The window sees the grant without its account, contact or member keys.
|
|
810
|
+
- It asks the home for a 30-day note, where a page asks for the home's
|
|
811
|
+
default.
|
|
812
|
+
|
|
813
|
+
### The home's address
|
|
814
|
+
|
|
815
|
+
`homeAddress(input)` turns what a person typed into the home's connect page:
|
|
816
|
+
|
|
817
|
+
```ts
|
|
818
|
+
import { homeAddress } from '@minca/core/session';
|
|
819
|
+
|
|
820
|
+
homeAddress('minca.example.com'); // 'https://minca.example.com/connect'
|
|
821
|
+
```
|
|
822
|
+
|
|
823
|
+
- With no scheme it adds `https://`, or `http://` for `localhost`,
|
|
824
|
+
`127.0.0.1` and `[::1]`.
|
|
825
|
+
- The host must be a loopback name, or a domain with a TLD of two letters or
|
|
826
|
+
more.
|
|
827
|
+
- The scheme must be `https:`, or `http:` on loopback.
|
|
828
|
+
- An empty path or `/` becomes `/connect`. Query and fragment are dropped.
|
|
829
|
+
|
|
830
|
+
### Asking the home
|
|
831
|
+
|
|
832
|
+
`connectToHome`, and `proposeToHome` for a proposal, open the home in a popup
|
|
833
|
+
named `minca-home` (`popup,width=460,height=720`). They send the request to
|
|
834
|
+
the home's origin only, every 500 ms, until the home answers. They check every
|
|
835
|
+
500 ms whether the person closed the popup, and give up after 10 minutes by
|
|
836
|
+
default.
|
|
837
|
+
|
|
838
|
+
### Starting the node
|
|
839
|
+
|
|
840
|
+
[`startConnectedNode`](https://minca.dev/api/session/functions/startConnectedNode/) starts a
|
|
841
|
+
node with:
|
|
842
|
+
|
|
843
|
+
- `signer`: `grantSigner(grant)`, so `did` is `grant.did`;
|
|
844
|
+
- `sessionKey`: the app's key;
|
|
845
|
+
- stores: `indexedDBStores('minca-app:<grant.did>')` unless given;
|
|
846
|
+
- `cache: {}` unless `cache: false`;
|
|
847
|
+
- `accountKey`, `contactKey` and `contactsSpace` from the grant when there,
|
|
848
|
+
never `contactKey` under a records-only note;
|
|
849
|
+
- relays: the app's plus `grant.relays`.
|
|
850
|
+
|
|
851
|
+
It then joins each granted space it doesn't hold yet, with its `memberKey`.
|
|
852
|
+
The desktop app's node and the agent on a computer start the same way, from
|
|
853
|
+
their own folders.
|
|
854
|
+
|
|
855
|
+
### The connection
|
|
856
|
+
|
|
857
|
+
`createMincaConnection(config)` is the app's version of [sign-in](sign-in.md).
|
|
858
|
+
It takes a [`MincaConnectionConfig`](https://minca.dev/api/session/interfaces/MincaConnectionConfig/),
|
|
859
|
+
and its status is a [`ConnectionStatus`](https://minca.dev/api/session/type-aliases/ConnectionStatus/).
|
|
860
|
+
|
|
861
|
+
- With `worker`, the node runs in a worker. If the worker fails to load or
|
|
862
|
+
doesn't start the node within 30 seconds (`WorkerNotStarted`), the node runs
|
|
863
|
+
in the page instead. A worker that started and refused passes its reason on.
|
|
864
|
+
- It turns `expired` when the grant's `expiresAt` passes.
|
|
865
|
+
- When the node sees its note revoked (`revoked`), the connection forgets that
|
|
866
|
+
account's grant and key.
|
|
867
|
+
- `propose(automations)` sends a proposal to the grant's home.
|
|
868
|
+
|
|
869
|
+
### Several accounts
|
|
870
|
+
|
|
871
|
+
A person can connect more than one account. The connection keeps a grant for
|
|
872
|
+
each and acts for one at a time. `state.accounts` lists them as
|
|
873
|
+
[`ConnectedAccount`](https://minca.dev/api/session/interfaces/ConnectedAccount/)s, in the order
|
|
874
|
+
first connected.
|
|
875
|
+
|
|
876
|
+
- `start()` acts for the account `account(accounts)` picks, else the one used
|
|
852
877
|
last, else the first.
|
|
853
|
-
- `use(did)`
|
|
854
|
-
|
|
855
|
-
|
|
856
|
-
|
|
857
|
-
|
|
858
|
-
|
|
859
|
-
|
|
860
|
-
|
|
861
|
-
|
|
862
|
-
|
|
863
|
-
|
|
864
|
-
|
|
865
|
-
|
|
866
|
-
|
|
867
|
-
|
|
868
|
-
|
|
869
|
-
|
|
870
|
-
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
|
|
874
|
-
|
|
875
|
-
|
|
876
|
-
|
|
877
|
-
|
|
878
|
-
|
|
879
|
-
|
|
880
|
-
|
|
881
|
-
|
|
882
|
-
|
|
883
|
-
|
|
884
|
-
`
|
|
885
|
-
|
|
886
|
-
|
|
887
|
-
|
|
888
|
-
|
|
889
|
-
|
|
890
|
-
|
|
878
|
+
- `use(did)` switches to another connected account without asking the home.
|
|
879
|
+
The old node closes, and one for this account starts, with its own stores.
|
|
880
|
+
- `connect(home?)` asks with a new key, for whichever account the person
|
|
881
|
+
picks at the home: a new one, or one already connected, whose grant it
|
|
882
|
+
renews. No key is ever used to ask twice, since a key that asked once may
|
|
883
|
+
hold a note from any account the home was signed in as. The renewed account
|
|
884
|
+
gets the new key and the old one is forgotten. The home revokes nothing, and
|
|
885
|
+
what the old key wrote stands.
|
|
886
|
+
- While `connect` waits, an app acting for an account stays `ready`. A grant
|
|
887
|
+
whose node won't start is kept, and the status is `disconnected` with why.
|
|
888
|
+
- `disconnect(did?)` forgets an account's grant and key, by default the
|
|
889
|
+
current one, and acts for the next account, or none. Disconnected at the
|
|
890
|
+
home instead, it acts for none, with `error` saying why.
|
|
891
|
+
|
|
892
|
+
Each grant is made out to a key of its own, `account-<uuid>` in `appKey`'s
|
|
893
|
+
store (or `keys`), so peers never see one key act for two accounts. Grants
|
|
894
|
+
live in `localStorage` under `minca.grants` (`[{ grant, keyName }]`), the
|
|
895
|
+
current account under `minca.account`, and the chosen home under `minca.home`
|
|
896
|
+
(the config's `home` is only a default). A grant whose `v` isn't
|
|
897
|
+
`GRANT_VERSION` (2) is dropped. An expired one stays, and opens as `expired`.
|
|
898
|
+
|
|
899
|
+
Each tab acts for its own account, and sees other tabs' changes to
|
|
900
|
+
`state.accounts`. A tab whose account was connected again elsewhere keeps
|
|
901
|
+
its key until it restarts, then takes the newer grant. One whose key was
|
|
902
|
+
revoked takes up a newer grant rather than forgetting it. A shared worker
|
|
903
|
+
runs a node per key. Switching again before a node has started closes it.
|
|
904
|
+
[Spec 06 §2.10](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md).
|
|
905
|
+
|
|
906
|
+
### Showing notifications
|
|
907
|
+
|
|
908
|
+
An app shows its own notifications with
|
|
909
|
+
`watchNotifications(node, { origin?, onNotify })`. It needs the account key,
|
|
910
|
+
so an app with `scope: account`. It reads the account's automations for the
|
|
911
|
+
app's origin, and calls `onNotify({ automation, record })` for each record
|
|
912
|
+
that arrives matching one.
|
|
913
|
+
|
|
914
|
+
A record matches when the automation isn't paused, and the record is in its
|
|
915
|
+
collection and one of its spaces, created after `since` and within the last
|
|
916
|
+
24 hours, by another account when `others` is set, and its `where` holds,
|
|
917
|
+
with `$me` the account. What the node held before it started is never news,
|
|
918
|
+
and nor is what a collection held when an automation first looked there.
|
|
919
|
+
|
|
920
|
+
How to show a match is up to the app. A "Notify me" button is usually where a
|
|
921
|
+
proposal starts.
|
|
922
|
+
|
|
923
|
+
For a list of what happened, pass `onActivity` too. After each change it gets
|
|
924
|
+
what the automations match now, newest first, up to 50, each record once under
|
|
925
|
+
the automation that asks about it most particularly. A match is dated by what
|
|
926
|
+
set it off, and listed if it would have notified when that was written, so
|
|
927
|
+
the 24 hours don't apply. It comes from the records, so it holds what arrived
|
|
928
|
+
while the app was closed, and devices holding the same records list the same.
|
|
929
|
+
Like notifications, it looks at the newest 50 records of a collection, by the
|
|
930
|
+
time their writers gave them, so an older match drops out under newer ones. A
|
|
931
|
+
match dated more than five minutes ahead waits for its time.
|
|
932
|
+
|
|
933
|
+
```js
|
|
934
|
+
watchNotifications(node, {
|
|
935
|
+
onNotify: ({ automation, record }) => showPopup(automation, record),
|
|
936
|
+
onActivity: (matches) => setActivity(matches),
|
|
937
|
+
});
|
|
938
|
+
```
|
|
939
|
+
|
|
940
|
+
What the person has read of it is the app's to keep: a time in the account
|
|
941
|
+
registry, say, and what is newer counts as new. A record that arrives late,
|
|
942
|
+
dated before that time, then isn't new, though it still notifies within its
|
|
943
|
+
24 hours.
|
|
891
944
|
|
|
892
945
|
## Carriers, hosting and notifications
|
|
893
946
|
|
|
894
|
-
|
|
895
|
-
are
|
|
896
|
-
|
|
897
|
-
|
|
898
|
-
|
|
899
|
-
|
|
900
|
-
|
|
901
|
-
|
|
902
|
-
|
|
903
|
-
|
|
904
|
-
|
|
905
|
-
|
|
906
|
-
|
|
907
|
-
|
|
908
|
-
|
|
909
|
-
|
|
910
|
-
space
|
|
911
|
-
|
|
912
|
-
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
|
|
916
|
-
|
|
917
|
-
|
|
918
|
-
|
|
919
|
-
|
|
920
|
-
|
|
921
|
-
|
|
922
|
-
|
|
923
|
-
|
|
924
|
-
|
|
925
|
-
|
|
926
|
-
|
|
927
|
-
|
|
928
|
-
|
|
929
|
-
|
|
930
|
-
|
|
931
|
-
|
|
932
|
-
|
|
933
|
-
|
|
934
|
-
|
|
935
|
-
|
|
936
|
-
|
|
937
|
-
|
|
938
|
-
|
|
939
|
-
|
|
940
|
-
|
|
941
|
-
|
|
942
|
-
|
|
943
|
-
the
|
|
944
|
-
|
|
945
|
-
|
|
946
|
-
|
|
947
|
-
|
|
948
|
-
|
|
949
|
-
|
|
950
|
-
|
|
951
|
-
|
|
952
|
-
|
|
953
|
-
|
|
954
|
-
|
|
955
|
-
|
|
956
|
-
|
|
957
|
-
|
|
958
|
-
|
|
959
|
-
|
|
960
|
-
|
|
961
|
-
|
|
962
|
-
|
|
963
|
-
|
|
964
|
-
|
|
965
|
-
|
|
966
|
-
|
|
967
|
-
|
|
968
|
-
|
|
969
|
-
|
|
970
|
-
`
|
|
971
|
-
|
|
972
|
-
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
|
|
978
|
-
|
|
979
|
-
|
|
980
|
-
|
|
981
|
-
`startBot
|
|
982
|
-
|
|
983
|
-
|
|
984
|
-
|
|
985
|
-
|
|
986
|
-
|
|
987
|
-
|
|
988
|
-
|
|
989
|
-
|
|
990
|
-
|
|
991
|
-
|
|
992
|
-
|
|
993
|
-
|
|
994
|
-
|
|
995
|
-
|
|
996
|
-
|
|
997
|
-
|
|
998
|
-
|
|
999
|
-
|
|
1000
|
-
|
|
1001
|
-
|
|
1002
|
-
|
|
1003
|
-
|
|
1004
|
-
|
|
1005
|
-
|
|
1006
|
-
|
|
1007
|
-
|
|
1008
|
-
|
|
947
|
+
A carrier is an always-on node that keeps the account's spaces online while
|
|
948
|
+
its devices are off. A host runs carriers for you, for a fee or for free.
|
|
949
|
+
[Spec 06 §4](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)
|
|
950
|
+
and [spec 08](https://github.com/leifriksheim/minca/blob/main/spec/08-hosting.md)
|
|
951
|
+
cover what goes over the wire.
|
|
952
|
+
|
|
953
|
+
### Carriers
|
|
954
|
+
|
|
955
|
+
`node.carriers.add({ did, name })` needs the account key. It derives the
|
|
956
|
+
carry space, writes the `sys.carrier` record, fills the carry space, and
|
|
957
|
+
returns `{ space, invite }` for the carrier to join with. The name is trimmed
|
|
958
|
+
to 80 characters, `Carrier` by default. Adding a carrier it already has
|
|
959
|
+
returns that one.
|
|
960
|
+
|
|
961
|
+
Carry spaces aren't kept in the node's list. Each is derived again from its
|
|
962
|
+
record. When the node starts, or the registry changes, it refills every carry
|
|
963
|
+
space in the background. That opens every space the account holds, which is
|
|
964
|
+
slow from a data folder, so signing in doesn't wait for it, and nor does
|
|
965
|
+
adding an automation. Adding a carrier writes its passes before it returns.
|
|
966
|
+
|
|
967
|
+
- `carriers.settled(waitMs)` waits for the refill under way, and says whether
|
|
968
|
+
it finished. Use it before a window closes.
|
|
969
|
+
- `carriers.reached(carrySpace, waitMs)` waits until the node is level with
|
|
970
|
+
the carrier in the carry space and the account registry. A node about to
|
|
971
|
+
close waits on it, so what it wrote for the carrier isn't lost.
|
|
972
|
+
- `carriers.remove(carrySpace)` writes `carry:closed` and marks the record
|
|
973
|
+
removed. The carry space stays open until the node closes, so the carrier
|
|
974
|
+
hears it.
|
|
975
|
+
|
|
976
|
+
### A space made just now
|
|
977
|
+
|
|
978
|
+
A new space lives only on the device that made it until a carrier syncs it.
|
|
979
|
+
An invite handed out before then, with the device closed, can't be used.
|
|
980
|
+
|
|
981
|
+
`node.spaces.carried(spaceId, { waitMs? })` is a short loading step for that.
|
|
982
|
+
If a carrier of the account is connected, it names it a keeper, writes its
|
|
983
|
+
pass, and waits up to `waitMs` (default 3 seconds) for it to be level. It
|
|
984
|
+
says whether it was, and is `false` at once with no carrier connected.
|
|
985
|
+
`contacts.ask` and `inbox.knock` wait on it, and return what it said as
|
|
986
|
+
`carried`, so the app can tell the person.
|
|
987
|
+
|
|
988
|
+
`node.spaces.reached(spaceId, peer, waitMs)` waits the same way for one peer,
|
|
989
|
+
named by its key, such as an app's key. It is `true` once that peer holds
|
|
990
|
+
everything this node does, and `false` when `waitMs` (at most a minute)
|
|
991
|
+
passed first. A connect page uses it to wait for the app to have what it
|
|
992
|
+
wrote.
|
|
993
|
+
|
|
994
|
+
### The account's own automations
|
|
995
|
+
|
|
996
|
+
`node.automations` needs the account key. It lists, adds, updates (`name`,
|
|
997
|
+
`paused`) and removes the account's own
|
|
998
|
+
[automations](automations.md#the-accounts-own), kept in its registry, and
|
|
999
|
+
copies a wake for each into every carry space. The reference home adds them
|
|
1000
|
+
when a person keeps an app's proposal, and lists them by app to pause or
|
|
1001
|
+
remove ([the account home's side](sign-in.md#the-account-homes-side)).
|
|
1002
|
+
|
|
1003
|
+
### A carrier's matches
|
|
1004
|
+
|
|
1005
|
+
When a version wakes one of the account's wakes, a `CarrierNode` sends a
|
|
1006
|
+
`wake` event with only the wake, the space, and the record's key, collection
|
|
1007
|
+
and `createdAt`. `wakes()` lists the wakes it holds. The desktop app shows
|
|
1008
|
+
these as notifications. The browser
|
|
1009
|
+
extension doesn't yet.
|
|
1010
|
+
|
|
1011
|
+
### Hosting
|
|
1012
|
+
|
|
1013
|
+
`node.hosting` pays a host and hands it the account's spaces. Its calls are
|
|
1014
|
+
on [`NodeHosting`](https://minca.dev/api/core/interfaces/NodeHosting/): start and stop using a
|
|
1015
|
+
host, pay into the account's balance or a space's own fund, ask for reminders,
|
|
1016
|
+
see how each host stands, and start a bot.
|
|
1017
|
+
|
|
1018
|
+
A few details:
|
|
1019
|
+
|
|
1020
|
+
- `list()` makes the carrier first if needed, named after the host's address.
|
|
1021
|
+
A second call waits for a handover already in flight. Every device runs it
|
|
1022
|
+
after each [reconcile](#following-the-account).
|
|
1023
|
+
- `pay` and `payForSpace` take `method` `checkout` or `request`, and
|
|
1024
|
+
`monthly` by card, as the host's `HostingView.fund` offers. They answer
|
|
1025
|
+
with `checkout`, a page to open in a new tab with no opener, or `request`,
|
|
1026
|
+
a payment for a wallet that the app shows. Call `list()` until the balance
|
|
1027
|
+
moves.
|
|
1028
|
+
- `remind` mails a link to confirm first.
|
|
1029
|
+
- `stop` sends `DELETE …/carry`, ignoring failure, removes the carrier and
|
|
1030
|
+
deletes the `sys.hosting` record.
|
|
1031
|
+
- `over(id)` returns `{ url, name, over }` with `over.until` and
|
|
1032
|
+
`over.reasons`, read from the receipts in `sys.hosting`. It asks no host.
|
|
1033
|
+
An agent may call it for a space it was given.
|
|
1034
|
+
- `startBot` makes an invite for `role` (by default as `spaces.invite` picks)
|
|
1035
|
+
and hands it over. The host holds the bot's keys, so tell the person first.
|
|
1036
|
+
[Spec 08 §3](https://github.com/leifriksheim/minca/blob/main/spec/08-hosting.md).
|
|
1037
|
+
|
|
1038
|
+
### Reaching hosts
|
|
1039
|
+
|
|
1040
|
+
A device reaches a host at the socket its description names (`peer`). Every
|
|
1041
|
+
open space holds a socket to each host in `sys.hosting`, and to each host the
|
|
1042
|
+
space names in `std.host`, and follows as those change. `network.nodes` adds
|
|
1043
|
+
sockets of its own, to every space.
|
|
1044
|
+
|
|
1045
|
+
`network.hosts` names hosts to look for the account registry at, before the
|
|
1046
|
+
account says which it uses. An app with a default host can then restore an
|
|
1047
|
+
account from its recovery code alone.
|
|
1048
|
+
|
|
1049
|
+
`network.reach(address)` decides whether the node may connect to an address
|
|
1050
|
+
it found rather than was given: a host or node a record or invite names, a
|
|
1051
|
+
relay a space or invite names, a short link's place, a host it asks to
|
|
1052
|
+
describe itself. Its own `relays`, `nodes` and `hosts` are always allowed,
|
|
1053
|
+
and without `reach`, so is everything. A refused host isn't asked, so
|
|
1054
|
+
`hosting` calls fail. A refused node or relay isn't dialled. Use it for a node
|
|
1055
|
+
a server runs for someone else, such as the MCP service's: what that node
|
|
1056
|
+
reads isn't the server's to trust, and must not make it connect inside its
|
|
1057
|
+
own network.
|
|
1058
|
+
|
|
1059
|
+
A device waits 15 seconds for a host to answer, and a minute for `startBot`.
|
|
1060
|
+
No answer in time is a `HostError` with status 0, whose message names the
|
|
1061
|
+
address. `describeHost(url, timeoutMs?)` takes another limit. `list()` and
|
|
1062
|
+
`space(id)` don't throw it. They return that host's view with `error` set,
|
|
1063
|
+
so one host that is down doesn't hide the others.
|
|
1064
|
+
|
|
1065
|
+
### The reference host
|
|
1066
|
+
|
|
1067
|
+
`minca host` makes these choices of its own:
|
|
1068
|
+
|
|
1069
|
+
- A lapsed subscription is kept for `graceDays` (default 30) after
|
|
1070
|
+
`paidUntil`, and swept out hourly (`sweepMs`).
|
|
1071
|
+
- It measures each carried space's folder at most every ten minutes. Each
|
|
1072
|
+
status gives the total as `bytes`, and `quota` from `MINCA_HOST_QUOTA_GB`
|
|
1073
|
+
(none unless set).
|
|
1074
|
+
- At its quota, an account's carry space takes no new space (`full`). What it
|
|
1075
|
+
carries stays and keeps syncing, and a space that waited is taken once
|
|
1076
|
+
there's room.
|
|
1077
|
+
|
|
1078
|
+
With `limits` (`MINCA_HOST_FREE_GB`), a subscription is active with nothing
|
|
1079
|
+
paid, on the `free` plan until it pays, with its quota by plan. A device
|
|
1080
|
+
hands such a host its carry space as it would a free one. A space paid for by
|
|
1081
|
+
its own fund takes none of its members' room. The host counts each space's
|
|
1082
|
+
writers as versions arrive (`onArrived`) and its readers as sockets prove
|
|
1083
|
+
themselves (`onPeer`), and once an hour (`evaluate`) holds each space to the
|
|
1084
|
+
free line. Past a space's `until`, every account's carry space stops carrying
|
|
1085
|
+
it (`skip`), while the space's own subscription still may. Each change is a
|
|
1086
|
+
line in the host's log.
|
|
1087
|
+
[Spec 08 §1.1](https://github.com/leifriksheim/minca/blob/main/spec/08-hosting.md).
|
|
1009
1088
|
|
|
1010
1089
|
### A space paying for itself
|
|
1011
1090
|
|
|
1012
|
-
A
|
|
1013
|
-
which only members granted
|
|
1014
|
-
`std.host` to admins and
|
|
1015
|
-
|
|
1016
|
-
|
|
1017
|
-
|
|
1018
|
-
|
|
1019
|
-
Every device holding the space's key
|
|
1020
|
-
|
|
1021
|
-
|
|
1022
|
-
|
|
1023
|
-
|
|
1024
|
-
|
|
1025
|
-
|
|
1026
|
-
|
|
1027
|
-
|
|
1028
|
-
`node.hosting.space(id)` does the same at once and returns each host's view:
|
|
1029
|
-
its name, key, status (
|
|
1030
|
-
|
|
1031
|
-
|
|
1032
|
-
|
|
1033
|
-
|
|
1034
|
-
|
|
1035
|
-
|
|
1036
|
-
`node.hosting.stopForSpace(id, url)` stops a space using a host
|
|
1037
|
-
|
|
1038
|
-
|
|
1039
|
-
|
|
1040
|
-
|
|
1041
|
-
|
|
1042
|
-
|
|
1043
|
-
`/member/remove` on it, and
|
|
1044
|
-
|
|
1045
|
-
|
|
1046
|
-
|
|
1047
|
-
|
|
1091
|
+
A community can pay for its own hosting. It names its hosts in `std.host`
|
|
1092
|
+
records ([standard library](standard-library.md)), which only members granted
|
|
1093
|
+
it may write. The `community` template leaves `std.host` to admins and
|
|
1094
|
+
moderators (`STAFF_COLLECTIONS`). The host then keeps the space under a
|
|
1095
|
+
subscription of its own, `space:<id>`, with a fund anyone can add to. The
|
|
1096
|
+
fund pays for keeping it online and for its bots.
|
|
1097
|
+
|
|
1098
|
+
Every device holding the space's key looks at the hosts the space names: when
|
|
1099
|
+
it takes a role there, at once when the hosts change, and otherwise at most
|
|
1100
|
+
every ten minutes. Agents and carriers don't. For each host it reads the
|
|
1101
|
+
description, refuses one whose key isn't the one the record names, asks for
|
|
1102
|
+
the status, and hands over the space's pass when the host is paid (or free
|
|
1103
|
+
and not lapsed) and doesn't carry the space yet, or carries it with an older
|
|
1104
|
+
read key. It looks only where the space defines `std.host`, so a space held
|
|
1105
|
+
in part isn't made to hold it.
|
|
1106
|
+
|
|
1107
|
+
`node.hosting.space(id)` does the same at once, and returns each host's view:
|
|
1108
|
+
its name, key, status (the fund's `balance`, its `daily` spend and the `bots`
|
|
1109
|
+
running), whether it is `free`, and `fund`, how money goes in. Show `fund` to
|
|
1110
|
+
anyone who wants to chip in, and pay with `payForSpace`. A host with neither
|
|
1111
|
+
`free` nor `fund` takes no communities. A host that couldn't be asked has
|
|
1112
|
+
`error` and no status. An agent may call `space` for a space it was given,
|
|
1113
|
+
but paying is a person's.
|
|
1114
|
+
|
|
1115
|
+
`node.hosting.stopForSpace(id, url)` stops a space using a host. It asks the
|
|
1116
|
+
host which bots it runs there, deletes the `std.host` record first so no
|
|
1117
|
+
device hands the host anything new, removes those bots, and gives a private
|
|
1118
|
+
space a new key if the host had it, or can't be asked. Removing a bot
|
|
1119
|
+
changes the key by itself. With no bot removed, it calls `changeKey`. It
|
|
1120
|
+
answers `{ bots, newKey }`.
|
|
1121
|
+
|
|
1122
|
+
It removes a bot only where the account may run `/member/remove` on it, and
|
|
1123
|
+
changes the key only with `/key/change`. Without either, only the record
|
|
1124
|
+
goes, and the answer is `{ bots: [], newKey: false }`. A host that was named
|
|
1125
|
+
but never handed the space costs no key change.
|
|
1126
|
+
|
|
1127
|
+
No call asks the host to drop what it has. It keeps the space, unreadable,
|
|
1128
|
+
for as long as the space's subscription is paid, and the fund keeps its money
|
|
1048
1129
|
([#220](https://github.com/leifriksheim/minca/issues/220)).
|
|
1049
1130
|
|
|
1050
|
-
_Source: `packages/core/src/node/node-hosting.ts` (`keepSpaceHosts`, `askSpaceHost`, `hosting.space`), `packages/core/src/session/hosting.ts` (`describeHost`, `HostError`). Tests: `packages/cli/tests/host.test.ts` ("a space paying for itself", "an address that is not a host, or one that is down", "bots a host runs": the two on stopping a space's host)._
|
|
1051
|
-
|
|
1052
1131
|
## The inbox
|
|
1053
1132
|
|
|
1054
|
-
|
|
1055
|
-
|
|
1056
|
-
|
|
1057
|
-
|
|
1058
|
-
|
|
1059
|
-
|
|
1060
|
-
|
|
1061
|
-
|
|
1062
|
-
|
|
1063
|
-
|
|
1064
|
-
|
|
1065
|
-
|
|
1066
|
-
|
|
1067
|
-
|
|
1068
|
-
|
|
1133
|
+
The inbox is where strangers knock to start a conversation, using a code, a
|
|
1134
|
+
link or a username. `node.inbox` needs the contact key
|
|
1135
|
+
([inbox](inbox.md), [spec 07](https://github.com/leifriksheim/minca/blob/main/spec/07-inbox.md)).
|
|
1136
|
+
|
|
1137
|
+
Its calls are on [`NodeInbox`](https://minca.dev/api/core/interfaces/NodeInbox/): open,
|
|
1138
|
+
rotate and clear the inbox, claim a username, knock, and list, accept or
|
|
1139
|
+
dismiss the knocks that arrive. `get()` returns an
|
|
1140
|
+
[`InboxView`](https://minca.dev/api/core/interfaces/InboxView/), with the code to hand out.
|
|
1141
|
+
|
|
1142
|
+
A username follows the inbox. `rotate` and `open` point it at the new code,
|
|
1143
|
+
and `knocks` renews it a month before it lapses. You hold one at a time.
|
|
1144
|
+
|
|
1145
|
+
`knocks()` fetches the inbox from every mailbox it names, opens and checks
|
|
1146
|
+
each knock (caching the results by id), and settles knocks you sent. Each is
|
|
1147
|
+
a [`KnockView`](https://minca.dev/api/core/interfaces/KnockView/). Knocking and accepting both follow
|
|
1148
|
+
[the exchange](inbox.md#the-exchange), and need whole-account access.
|
|
1149
|
+
[Spec 07 §6](https://github.com/leifriksheim/minca/blob/main/spec/07-inbox.md).
|
|
1069
1150
|
|
|
1070
1151
|
## Client conveniences
|
|
1071
1152
|
|
|
1072
|
-
These
|
|
1073
|
-
likes.
|
|
1074
|
-
|
|
1075
|
-
-
|
|
1076
|
-
|
|
1077
|
-
|
|
1078
|
-
|
|
1079
|
-
|
|
1080
|
-
|
|
1081
|
-
|
|
1082
|
-
|
|
1083
|
-
|
|
1084
|
-
|
|
1085
|
-
|
|
1086
|
-
|
|
1087
|
-
|
|
1088
|
-
|
|
1089
|
-
|
|
1090
|
-
|
|
1153
|
+
These aren't protocol. Another client may draw sign-in and
|
|
1154
|
+
[calls](../../calls/README.md) however it likes.
|
|
1155
|
+
|
|
1156
|
+
Sign-in has no drawn screens in the library: a page draws its own on
|
|
1157
|
+
[`createMincaAuth`](sign-in.md), as the account home does.
|
|
1158
|
+
|
|
1159
|
+
## React
|
|
1160
|
+
|
|
1161
|
+
`@minca/react` follows sign-in or the connection, and keeps what you read
|
|
1162
|
+
live. `MincaProvider` goes at the top, given an `auth` or a `connection`;
|
|
1163
|
+
`useMinca`, `useAuth`, `useSession`, `useConnection` and `useAccount` read
|
|
1164
|
+
it. Below it, hooks such as `useNode`,
|
|
1165
|
+
`useSpaces`, `useQuery`, `useRecord` and `useCan` read and keep current what
|
|
1166
|
+
you show, with `useLive` and `useWatched` for anything else. Each one, and what
|
|
1167
|
+
it gives, is in the [React reference](https://minca.dev/api/react/).
|
|
1168
|
+
|
|
1169
|
+
`result.complete` is false while an app that holds only part of a space is
|
|
1170
|
+
still fetching a collection. Show "Loading…", not "Nothing here".
|
|
1171
|
+
|
|
1172
|
+
An app given the whole account sees every space in it. `useSpaces({ having: [todos] })`
|
|
1173
|
+
lists only the spaces that define those collections.
|
|
1174
|
+
|
|
1175
|
+
Calls have their own, `CallsProvider` and `useCalls`, in `@minca/calls/react`.
|