@niscorp/moss 0.9.2 → 0.10.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/CHANGELOG.md +122 -0
- package/DESIGN.md +58 -55
- package/DOCS.md +280 -170
- package/README.md +5 -5
- package/dist/{chunk-PVZMCEBX.cjs → chunk-3CKBKTXA.cjs} +2 -2
- package/dist/chunk-3CKBKTXA.cjs.map +1 -0
- package/dist/{chunk-FUJRIO4N.js → chunk-3PL4AH4I.js} +4 -4
- package/dist/{chunk-FUJRIO4N.js.map → chunk-3PL4AH4I.js.map} +1 -1
- package/dist/{chunk-QAHDSRPK.js → chunk-4URQHVYG.js} +2 -2
- package/dist/chunk-4URQHVYG.js.map +1 -0
- package/dist/{chunk-6ZWMC2OV.cjs → chunk-6ACVHHFK.cjs} +33 -30
- package/dist/chunk-6ACVHHFK.cjs.map +1 -0
- package/dist/{chunk-IUJ2TRNB.cjs → chunk-7MOEKAVC.cjs} +6 -6
- package/dist/{chunk-IUJ2TRNB.cjs.map → chunk-7MOEKAVC.cjs.map} +1 -1
- package/dist/{chunk-NCQBGK3E.cjs → chunk-BFA76AKR.cjs} +4 -4
- package/dist/chunk-BFA76AKR.cjs.map +1 -0
- package/dist/{chunk-T5BRTFKP.js → chunk-DSVRFAGX.js} +3 -3
- package/dist/{chunk-T5BRTFKP.js.map → chunk-DSVRFAGX.js.map} +1 -1
- package/dist/{chunk-IW3A2YIC.js → chunk-EYWD733E.js} +3 -3
- package/dist/{chunk-IW3A2YIC.js.map → chunk-EYWD733E.js.map} +1 -1
- package/dist/{chunk-IY5BOFLK.cjs → chunk-G4P3XEVM.cjs} +19 -19
- package/dist/chunk-G4P3XEVM.cjs.map +1 -0
- package/dist/{chunk-6QPTMKRE.cjs → chunk-HUP7CZ7X.cjs} +6 -6
- package/dist/{chunk-6QPTMKRE.cjs.map → chunk-HUP7CZ7X.cjs.map} +1 -1
- package/dist/{chunk-VKQPOZDJ.cjs → chunk-LTS4AM6T.cjs} +4 -4
- package/dist/chunk-LTS4AM6T.cjs.map +1 -0
- package/dist/{chunk-UTFOMFCH.js → chunk-MEHCZECW.js} +5 -5
- package/dist/chunk-MEHCZECW.js.map +1 -0
- package/dist/{chunk-WMIJU6ZZ.js → chunk-MYPK5YZR.js} +297 -206
- package/dist/chunk-MYPK5YZR.js.map +1 -0
- package/dist/{chunk-TKXYPO2Y.js → chunk-NUX5MH4I.js} +4 -4
- package/dist/chunk-NUX5MH4I.js.map +1 -0
- package/dist/{chunk-KVXP6OTW.cjs → chunk-UVY5ZPWW.cjs} +373 -282
- package/dist/chunk-UVY5ZPWW.cjs.map +1 -0
- package/dist/{chunk-5ZB7FZ2J.js → chunk-VYYDLGQ2.js} +29 -26
- package/dist/chunk-VYYDLGQ2.js.map +1 -0
- package/dist/{chunk-NRZ3Z2FF.js → chunk-WKZWSWOJ.js} +4 -4
- package/dist/chunk-WKZWSWOJ.js.map +1 -0
- package/dist/{chunk-KMZT6NVL.cjs → chunk-XH6TSWG4.cjs} +7 -7
- package/dist/{chunk-KMZT6NVL.cjs.map → chunk-XH6TSWG4.cjs.map} +1 -1
- package/dist/client.cjs +5 -5
- package/dist/client.js +2 -2
- package/dist/{document-deAs7Dre.d.cts → document-DvhT_HaJ.d.cts} +3 -2
- package/dist/{document-C3aS9uiW.d.ts → document-iKaRinZE.d.ts} +3 -2
- package/dist/{index-CSEo7Tys.d.ts → index-DWj3_0Zg.d.cts} +3 -0
- package/dist/{index-CSEo7Tys.d.cts → index-DWj3_0Zg.d.ts} +3 -0
- package/dist/index.cjs +16 -16
- package/dist/index.d.cts +4 -4
- package/dist/index.d.ts +4 -4
- package/dist/index.js +4 -4
- package/dist/integrations.cjs +27 -18
- package/dist/integrations.cjs.map +1 -1
- package/dist/integrations.d.cts +1 -1
- package/dist/integrations.d.ts +1 -1
- package/dist/integrations.js +25 -16
- package/dist/integrations.js.map +1 -1
- package/dist/node.cjs +9 -9
- package/dist/node.d.cts +2 -2
- package/dist/node.d.ts +2 -2
- package/dist/node.js +5 -5
- package/dist/protocol.cjs +5 -5
- package/dist/protocol.js +1 -1
- package/dist/terminal/dom/index.cjs +3 -3
- package/dist/terminal/dom/index.js +1 -1
- package/dist/terminal/dom/server.cjs +2 -2
- package/dist/terminal/dom/server.js +1 -1
- package/dist/terminal/index.cjs +3 -3
- package/dist/terminal/index.js +2 -2
- package/dist/terminal/ink/index.js.map +1 -1
- package/dist/terminal/react/index.cjs +9 -9
- package/dist/terminal/react/index.cjs.map +1 -1
- package/dist/terminal/react/index.js +4 -4
- package/dist/terminal/react/index.js.map +1 -1
- package/dist/terminal/react/server.cjs +4 -4
- package/dist/terminal/react/server.js +2 -2
- package/dist/terminal/tty/index.cjs +12 -12
- package/dist/terminal/tty/index.cjs.map +1 -1
- package/dist/terminal/tty/index.js +6 -6
- package/dist/terminal/tty/index.js.map +1 -1
- package/dist/terminal/vue/index.cjs +9 -9
- package/dist/terminal/vue/index.cjs.map +1 -1
- package/dist/terminal/vue/index.js +4 -4
- package/dist/terminal/vue/index.js.map +1 -1
- package/dist/terminal/vue/server.cjs +4 -4
- package/dist/terminal/vue/server.js +2 -2
- package/dist/tide.d.cts +1 -1
- package/dist/tide.d.ts +1 -1
- package/dist/unverified.cjs +4 -4
- package/dist/unverified.js +3 -3
- package/dist/vite.cjs +36 -10
- package/dist/vite.cjs.map +1 -1
- package/dist/vite.d.cts +2 -2
- package/dist/vite.d.ts +2 -2
- package/dist/vite.js +31 -5
- package/dist/vite.js.map +1 -1
- package/package.json +13 -13
- package/dist/chunk-5ZB7FZ2J.js.map +0 -1
- package/dist/chunk-6ZWMC2OV.cjs.map +0 -1
- package/dist/chunk-IY5BOFLK.cjs.map +0 -1
- package/dist/chunk-KVXP6OTW.cjs.map +0 -1
- package/dist/chunk-NCQBGK3E.cjs.map +0 -1
- package/dist/chunk-NRZ3Z2FF.js.map +0 -1
- package/dist/chunk-PVZMCEBX.cjs.map +0 -1
- package/dist/chunk-QAHDSRPK.js.map +0 -1
- package/dist/chunk-TKXYPO2Y.js.map +0 -1
- package/dist/chunk-UTFOMFCH.js.map +0 -1
- package/dist/chunk-VKQPOZDJ.cjs.map +0 -1
- package/dist/chunk-WMIJU6ZZ.js.map +0 -1
package/DOCS.md
CHANGED
|
@@ -59,6 +59,7 @@ type NiscApp = {
|
|
|
59
59
|
shell?: ShellManifest; // the server shell, as data — THE APP
|
|
60
60
|
pages?: Record<string, PageManifest>; // what is drawn at a path and kept by nothing
|
|
61
61
|
grammars?: readonly Sequence[]; // the app's own strata grammar sequences
|
|
62
|
+
upgradedColumns?: UpgradedColumns; // JSON columns every vex read returns upgraded
|
|
62
63
|
// the code seams
|
|
63
64
|
scope?: (principal: string | null, identity?: IdentityRecord) => Record<string, unknown>;
|
|
64
65
|
identity?: { as?: string; resolve: (principal, read) => Promise<IdentityRecord> };
|
|
@@ -87,10 +88,10 @@ reaction's `run` — and `features`. Absent `shell`, the app serves data only
|
|
|
87
88
|
an org). Moss always injects `{ userId }` (the principal; `'anonymous'` for
|
|
88
89
|
nobody signed in); this contributes the rest, merged
|
|
89
90
|
server-side and asked per request, so a value derived from the clock is
|
|
90
|
-
never
|
|
91
|
+
never kept for a session. Synchronous. `identity` is the record
|
|
91
92
|
`identity.resolve` answered: absent for nobody signed in, and in an app with
|
|
92
93
|
no `identity` seam. What `scope` answers is merged over that record's
|
|
93
|
-
`scope`, the values that are
|
|
94
|
+
`scope`, the values that are kept for the session.
|
|
94
95
|
- `identity.resolve(principal, read)` — who a principal is, resolved once per
|
|
95
96
|
session and cached by moss (bounded by `runtime.identityMax` /
|
|
96
97
|
`identityIdleMs`, re-resolved every `sessionRevalidateMs`). Returns an
|
|
@@ -112,7 +113,7 @@ reaction's `run` — and `features`. Absent `shell`, the app serves data only
|
|
|
112
113
|
twice.` A map of handlers by id still works and is deprecated.
|
|
113
114
|
**`server.checkFunctions()`** builds nobody's shell once, drops it, and reads
|
|
114
115
|
what its `functions(session)` returned, so what is wrong with the functions
|
|
115
|
-
is refused or said before anyone is served. The app calls it once it
|
|
116
|
+
is refused or said before anyone is served. The app calls it once it has
|
|
116
117
|
the server, as a session hook may reach for the server, after it has
|
|
117
118
|
mounted every route of its own, and before it listens. Nobody's shell
|
|
118
119
|
makes its reads in-process, and the server takes no route once it has
|
|
@@ -124,22 +125,22 @@ reaction's `run` — and `features`. Absent `shell`, the app serves data only
|
|
|
124
125
|
returned a map of handlers, which is deprecated: return a list of { id,
|
|
125
126
|
description, execute }.`, or `[moss] functions with no description:
|
|
126
127
|
auth.leave. Give each a description.` An empty description counts as none,
|
|
127
|
-
and a function given by a map has none. **A shell
|
|
128
|
+
and a function given by a map has none. **A shell has only the functions
|
|
128
129
|
its principal's roles grant**, in the charter's `functions` part (names or
|
|
129
130
|
globs, with `extends` and `deny`, as `actions`): a role with none may call
|
|
130
131
|
none, and an `fn:` endpoint to one it does not grant fails when it is called.
|
|
131
|
-
What a living shell
|
|
132
|
+
What a living shell has follows the roles an adopt answers, as its actions
|
|
132
133
|
do.
|
|
133
|
-
- **The boot is refused** where somebody
|
|
134
|
+
- **The boot is refused** where somebody is granted an action that calls a
|
|
134
135
|
function their roles do not grant, and **`server.checkFunctions()` refuses**
|
|
135
136
|
where an action, or a fragment the shells ship, calls a function the app
|
|
136
137
|
does not have (`"home" calls "auth.leave", which the app has no function
|
|
137
138
|
of`); an app with no `functions` has none. It reads the `fn:` endpoints of
|
|
138
|
-
the actions
|
|
139
|
+
the actions granted to each role on its own, each combination `wearable` or
|
|
139
140
|
`assignments` lists, and `public`, and of the fragments the shells ship,
|
|
140
141
|
and lists every call that is missing: `"member" hold "chrome.topbar",
|
|
141
142
|
which calls "auth.leave": their functions do not grant it`. A set handed
|
|
142
|
-
over while the app runs is
|
|
143
|
+
over while the app runs is checked the same way. A name with a template in it
|
|
143
144
|
(`fn: '{{$.saveFn}}'`) is worked out when it is called, and the shell's map
|
|
144
145
|
decides then.
|
|
145
146
|
- **`functions: ['*']`** grants every function, as an app had before this
|
|
@@ -181,7 +182,7 @@ reaction's `run` — and `features`. Absent `shell`, the app serves data only
|
|
|
181
182
|
`reconcile` step aims at it (nova's SHELL_DOCS.md, "A canvas that names its
|
|
182
183
|
own reconciler"): handed each row as written, it decides what is kept,
|
|
183
184
|
matched, moved and removed — several cards of one action on one list canvas,
|
|
184
|
-
matched by a key and kept in the list's order. Every shell moss builds
|
|
185
|
+
matched by a key and kept in the list's order. Every shell moss builds has
|
|
185
186
|
them, the app's and each page's, the one a document is drawn from and the
|
|
186
187
|
socket's: from one seed, a reconciler that answers the same rows the same
|
|
187
188
|
way places the same instances in both. A reconciler
|
|
@@ -190,15 +191,33 @@ reaction's `run` — and `features`. Absent `shell`, the app serves data only
|
|
|
190
191
|
app does not hand over: ``shell.canvases.1.reconcile: "keyed" is not a
|
|
191
192
|
reconciler the app hands over in `reconcilers` ``.
|
|
192
193
|
- `grammars` — strata sequences for documents only this app defines the shape
|
|
193
|
-
of (its kit's component props
|
|
194
|
-
grammars" below.
|
|
194
|
+
of (its kit's component props, and the values of its `upgradedColumns`). See
|
|
195
|
+
"Documents are read in this code's grammars" below.
|
|
196
|
+
- `upgradedColumns` — the app's JSON columns whose values are stamped in
|
|
197
|
+
another column of the row, keyed by table and column:
|
|
198
|
+
`{ answers: { plan: { stamp: 'grammar', kind: 'acme.answers/plan' } } }`, or
|
|
199
|
+
with the kind read from the row, `kind: { grammar: 'acme.notes', column: 'kind' }`,
|
|
200
|
+
and what a read does with a row that does not upgrade, `unreadable: 'refuse' | 'omit' | 'null'`.
|
|
201
|
+
Moss hands them to the app's engine, and to the one that answers intents,
|
|
202
|
+
with the upgrader it builds from nova's, Prism's and vex's grammars and the
|
|
203
|
+
app's `grammars`: every read through either returns those columns upgraded,
|
|
204
|
+
before its mapping. What a read must select and what a row that does not
|
|
205
|
+
upgrade does are vex's ([Upgraded columns](../vex/DOCS.md#upgraded-columns)).
|
|
206
|
+
Only the app's own tables can be named: a feature's tables, the
|
|
207
|
+
artifactory's and the generation pointer's are read by their owner's own
|
|
208
|
+
entries, which read them as stored. **The boot is refused** where a table
|
|
209
|
+
named is one of those, where a kind, or the grammar of a kind read from the
|
|
210
|
+
row, is in none of the upgrader's grammars, where a column or its stamp is not a json
|
|
211
|
+
column of the database, and where a seeded read in `entries` does not compile
|
|
212
|
+
(moss compiles each one at boot, and each one a refresh hands over, only for
|
|
213
|
+
an app that names `upgradedColumns`).
|
|
195
214
|
|
|
196
215
|
A `LayoutVariant` is `{ action: string; layout: LayoutNode }` — ring 2: the
|
|
197
216
|
charter's `layouts` section selects who is granted which variant id, and moss
|
|
198
217
|
puts the granted variant's layout where that action's layout is kept in the
|
|
199
218
|
shell ("Where an action's layout is kept", under `createServer`). The base is
|
|
200
219
|
the floor; variants enrich upward as grants. A role, or a combination
|
|
201
|
-
of roles somebody may wear, that
|
|
220
|
+
of roles somebody may wear, that is granted two variants of one action refuses the
|
|
202
221
|
boot, and so does a variant of an action the app does not have.
|
|
203
222
|
|
|
204
223
|
#### `ShellManifest`
|
|
@@ -227,15 +246,15 @@ they generated.
|
|
|
227
246
|
A `CanvasSeed` is an action id or `{ action, input?, with? }`, and a
|
|
228
247
|
`ShellCanvas` is nova's canvas config with `initial` widened to one seed or a
|
|
229
248
|
list of candidates. Neither type is exported by name: `ShellManifest['canvases']`
|
|
230
|
-
carries both. Of a list of candidates, the first action the principal
|
|
231
|
-
mounts; a canvas none of whose candidates they
|
|
249
|
+
carries both. Of a list of candidates, the first action the principal is granted
|
|
250
|
+
mounts; a canvas none of whose candidates they are granted starts empty. A canvas's
|
|
232
251
|
`reconcile` names one of the app's `reconcilers`.
|
|
233
252
|
|
|
234
253
|
`components` is the kit as the server knows it: each component's name, with
|
|
235
254
|
its `meta` (a `description`, and `propsSchema`, the zod schema of its props).
|
|
236
255
|
A name listed there is registered in the shell whether or not a layout of the
|
|
237
256
|
app uses it. The `components` of the app's own `shell` are also the kit a
|
|
238
|
-
bundle's layouts are
|
|
257
|
+
bundle's layouts are checked against at intake, and the one the integrations'
|
|
239
258
|
contract lists ([`@niscorp/moss/integrations`](#niscorpmossintegrations)): a
|
|
240
259
|
bundle's layout that uses a component not listed there is refused, and where
|
|
241
260
|
a component's `propsSchema` is a zod object, so is a prop it has no place for.
|
|
@@ -344,7 +363,7 @@ throw, and so do `set` and `delete` on its `layoutStore`, which is to read. A
|
|
|
344
363
|
definition read off it (`shell.getRuntime(id).definition`) is the action as it
|
|
345
364
|
was written, with the layout it is drawn with now in place: where moss keeps a
|
|
346
365
|
layout does not show. An action, a fragment, a canvas, a layout and the phrases reach a shell
|
|
347
|
-
through moss, which verifies them and decides who
|
|
366
|
+
through moss, which verifies them and decides who is granted them; added on the
|
|
348
367
|
shell directly they are not verified, are in nobody's catalog and are gone
|
|
349
368
|
when the shell is rebuilt. Everything else (reads, navigation, `dispatch`,
|
|
350
369
|
`publish`, the observers) works as on nova's `Shell`, which is still the
|
|
@@ -360,9 +379,9 @@ import type { ActionDefinition } from '@niscorp/nova';
|
|
|
360
379
|
const register = (session: FunctionSession, definition: ActionDefinition): void => unverifiedShell(session).registerAction(definition);
|
|
361
380
|
```
|
|
362
381
|
|
|
363
|
-
**A session says who is calling and
|
|
382
|
+
**A session says who is calling and has no key.** It carries no `runtime`
|
|
364
383
|
(the database pool, the operator key) and no `policy` (the
|
|
365
|
-
object the routes enforce for everybody
|
|
384
|
+
object the routes enforce for everybody wearing those roles). What app code
|
|
366
385
|
needs of either has a call:
|
|
367
386
|
|
|
368
387
|
- **A read or a write as the caller**: `session.wire`, the routes, enforced.
|
|
@@ -372,7 +391,8 @@ needs of either has a call:
|
|
|
372
391
|
intent and the shape. The query is written, compiled and run under the
|
|
373
392
|
policy and the scope values the routes serve this principal under, resolved
|
|
374
393
|
when it is asked: the writer is shown only the tables they may read, and a
|
|
375
|
-
query that reaches past their policy is refused.
|
|
394
|
+
query that reaches past their policy is refused. A replay of an entry that
|
|
395
|
+
declares a `reach` is served at that reach, as the routes serve it. It is kept in the cache the
|
|
376
396
|
routes replay from, so `answer.meta.cache.fingerprint` replays over
|
|
377
397
|
`session.wire` afterwards, for whoever the policy lets. Moss keeps one
|
|
378
398
|
engine for each `writers` object: hand over the same object each time. It
|
|
@@ -474,8 +494,18 @@ functions: (session) => [
|
|
|
474
494
|
theirs whose newest version was neither saved nor used within that time is
|
|
475
495
|
deleted, every version of it, by a sweep that runs as the server comes up and
|
|
476
496
|
then every hour. What is published for everybody never ages, and what the
|
|
477
|
-
build ships is not a row. Without the setting nothing is deleted. A limit
|
|
478
|
-
|
|
497
|
+
build ships is not a row. Without the setting nothing is deleted. A limit
|
|
498
|
+
that is not a whole number of milliseconds, or is under two hours
|
|
499
|
+
(7,200,000 ms), refuses the boot.
|
|
500
|
+
|
|
501
|
+
**Time the app is down counts as unused.** After a downtime longer than
|
|
502
|
+
`artifactsUnusedMs`, the sweep as the server comes up deletes everything of
|
|
503
|
+
everybody's that was not used since. With `runtime.artifactsUnusedSinceStart:
|
|
504
|
+
true` the time is counted only since this server started: the sweep deletes
|
|
505
|
+
nothing until the server has been up for `artifactsUnusedMs`, so what was
|
|
506
|
+
last used before the start is unused from the start on. Running time before
|
|
507
|
+
the start does not count either, and a server restarted more often than
|
|
508
|
+
`artifactsUnusedMs` deletes nothing.
|
|
479
509
|
- **It reaches its owner's open shells a moment after the save answers**, as a
|
|
480
510
|
saved layout does, and not before: a function that saves an action and
|
|
481
511
|
opens it in the same call finds it not there yet. One that is to be seen at
|
|
@@ -500,20 +530,20 @@ functions: (session) => [
|
|
|
500
530
|
endpoints, and where both define an endpoint of one name the action's is
|
|
501
531
|
the one called. What an assistant is told it may generate is the app's to
|
|
502
532
|
decide: it writes the prompt, and its own function calls `save`.
|
|
503
|
-
- **A generated action opens the actions its owner
|
|
533
|
+
- **A generated action opens the actions its owner is granted**, their own
|
|
504
534
|
generated ones among them, and no other: nova's audit is run on it with
|
|
505
535
|
those as its catalog, and what it finds refuses the save, as it does for a
|
|
506
536
|
saved layout. So do a component no shell of the app has, and a layout that
|
|
507
|
-
names a ref moss keeps a layout under (`action/…`, `canvas/…`, `frame`). A fragment is
|
|
508
|
-
layout and its endpoints, and not
|
|
509
|
-
a step of a fragment that opens an action its owner
|
|
537
|
+
names a ref moss keeps a layout under (`action/…`, `canvas/…`, `frame`). A fragment is checked against its schema, its id, its
|
|
538
|
+
layout and its endpoints, and not against that audit, which reads a whole action:
|
|
539
|
+
a step of a fragment that opens an action its owner is not granted is refused
|
|
510
540
|
by nova when it runs, because that action is not in their shell.
|
|
511
541
|
- **It is checked when it is saved and again when a shell is built.** One
|
|
512
542
|
that no longer passes (its owner lost the grant its read needs, say) is left
|
|
513
543
|
out of every shell built from then on, with a line (`[moss] the action "…"
|
|
514
544
|
of … is left out: …`).
|
|
515
545
|
- **A reset takes it out of its owner's shells**, and the layouts they saved
|
|
516
|
-
for it are not drawn while it is out: a layout whose action its
|
|
546
|
+
for it are not drawn while it is out: a layout whose action its owner has
|
|
517
547
|
no longer is not loaded. `list('layout')` still lists them. Going back to a
|
|
518
548
|
version of the action brings both back.
|
|
519
549
|
- **No action an app ships or hands over, and no fragment of a shell, has an
|
|
@@ -533,7 +563,7 @@ whose `principal` is their `userId`, and a row they insert or update carries
|
|
|
533
563
|
it, whatever the statement says. Vex keeps that rule on every read and every
|
|
534
564
|
write; moss's code passes no principal. **Who may save at all is the charter's**: a function that calls
|
|
535
565
|
`session.artifacts.save` is the app's, an action calls it, and the charter
|
|
536
|
-
says who
|
|
566
|
+
says who is granted that action. A session nobody is signed in to saves nothing
|
|
537
567
|
and lists nothing: everybody who is not signed in shares one `userId`.
|
|
538
568
|
|
|
539
569
|
- The layout is the principal's and nobody else's. Moss gives it its id, a
|
|
@@ -555,16 +585,17 @@ or write a row of another account.
|
|
|
555
585
|
|
|
556
586
|
**A read vex wrote** for a request (`session.answerIntent`) is saved under
|
|
557
587
|
the fingerprint vex gave it, with no body:
|
|
558
|
-
`session.artifacts.save([{ kind: 'read', id: 'fp_…' }])`.
|
|
559
|
-
from vex's own table and keeps it as written: the query,
|
|
560
|
-
its mapping, its shape and its intent
|
|
588
|
+
`session.artifacts.save([{ kind: 'read', id: 'fp_…', body: undefined }])`.
|
|
589
|
+
Moss takes the entry from vex's own table and keeps it as written: the query,
|
|
590
|
+
the Prism config of its mapping, its shape and its intent, so a read that
|
|
591
|
+
comes with a body is refused.
|
|
561
592
|
|
|
562
593
|
- **It is answered to the person who saved it and to nobody else.** When one
|
|
563
594
|
of their requests replays that fingerprint, moss answers it, compiled, from
|
|
564
595
|
their rows. Anybody else who sends the fingerprint gets what vex's own table
|
|
565
|
-
still
|
|
596
|
+
still has under it, as for any query vex wrote and nobody saved, and a
|
|
566
597
|
caller nobody is signed in for is never answered a saved read.
|
|
567
|
-
- **It is a query vex wrote, and is
|
|
598
|
+
- **It is a query vex wrote, and is kept as one.** Vex's limits apply to it
|
|
568
599
|
(`maxLimit`), as they do not to an entry the app ships. A request that names
|
|
569
600
|
its fingerprint with an intent and a shape is written anew by vex into its
|
|
570
601
|
own table; the saved read is what its owner is answered until they save the
|
|
@@ -589,12 +620,12 @@ its mapping, its shape and its intent.
|
|
|
589
620
|
|
|
590
621
|
**What a shell draws under an action's ref**, the first of these that there
|
|
591
622
|
is: the principal's own layout marked in use; the layout variant their roles
|
|
592
|
-
|
|
623
|
+
are granted (`app.layouts`); the layout published for everybody that is marked in use
|
|
593
624
|
(`server.defaults`); the layout the build ships.
|
|
594
625
|
|
|
595
626
|
**What is refused**, at a save and at a restore, in a sentence, with nothing
|
|
596
627
|
written: a body that is not `{ ref, layout, use? }`; a `ref` nothing is kept
|
|
597
|
-
under for the principal (an action they
|
|
628
|
+
under for the principal (an action they are not granted, or one that is not in
|
|
598
629
|
force; an action with no layout of its own, or one that names a layout of the
|
|
599
630
|
store by its id; any name that is none of `action/<id>`, `frame` and
|
|
600
631
|
`canvas/<id>`); a component no shell of
|
|
@@ -607,8 +638,8 @@ a control the action listens on that the layout leaves out, a control no
|
|
|
607
638
|
trigger handles). The same is asked of every saved layout when a shell is
|
|
608
639
|
built, there against the components of that shell alone: one that does not
|
|
609
640
|
pass is left out, what is under it is drawn, and a line says why (`[moss] the layout "…" of … is left out: …`). One whose ref
|
|
610
|
-
its
|
|
611
|
-
|
|
641
|
+
its owner's store keeps nothing under any more (the action left, or they
|
|
642
|
+
are granted it no longer) is not loaded and nothing is said.
|
|
612
643
|
|
|
613
644
|
**The layouts of the app's own shell** are saved with the same calls: its own
|
|
614
645
|
under `ref: 'frame'`, and a canvas's under `ref: 'canvas/<the canvas's id>'`.
|
|
@@ -640,20 +671,22 @@ true } }])`.
|
|
|
640
671
|
gives a shell a canvas when something is first pushed onto it, whether or not
|
|
641
672
|
its manifest declares it, and it is drawn where a layout has a canvas slot for
|
|
642
673
|
it (`{ component: 'CanvasSlot', props: { canvasId: 'notes' } }`). Moss reads
|
|
643
|
-
which canvases the layouts a shell is built from
|
|
674
|
+
which canvases the layouts a shell is built from have a slot for and its
|
|
644
675
|
manifest does not declare. Every layout counts (the frame, a canvas's, an
|
|
645
|
-
action's that the principal
|
|
676
|
+
action's that the principal is granted, a fragment's, one the app keeps in its
|
|
646
677
|
layout store), the build's and a saved or generated one alike. Once a layout
|
|
647
|
-
leaves force and no other
|
|
678
|
+
leaves force and no other has a slot for such a canvas, an open shell loses
|
|
648
679
|
the canvas, with what is mounted on it. A slot whose `canvasId` is worked out
|
|
649
680
|
when it is drawn (`'$.c.id'`, a template) counts for none. Moss gives a shell
|
|
650
681
|
no canvas, and the canvases a manifest declares are never taken out. What is
|
|
651
682
|
pushed onto a canvas after its slot went is mounted and drawn nowhere, as on
|
|
652
683
|
any canvas no layout has a slot for.
|
|
653
684
|
|
|
654
|
-
**
|
|
685
|
+
**A save, a restore and a reset each add rows and change none.** The one
|
|
686
|
+
column moss changes is `last_used_at`, and the one delete is the aging sweep's
|
|
687
|
+
("It ages out when nobody uses it"). `list` answers the latest version of each
|
|
655
688
|
of the principal's artifacts that has a body. `history` answers the versions
|
|
656
|
-
of one, the newest first (the newest 500). `restore` is a new save that
|
|
689
|
+
of one, the newest first (the newest 500). `restore` is a new save that contains
|
|
657
690
|
a copy of a version and says which (`copiedFrom`); it is checked as a save
|
|
658
691
|
is. `reset` is a new save whose version has no body: none of the principal's
|
|
659
692
|
is in force under that id, and what is under it is drawn again. A reset is a
|
|
@@ -663,7 +696,7 @@ drawn. The next save that marks one for that ref, or takes the one in use out
|
|
|
663
696
|
(a reset, or a save of it without the mark), takes the mark off the rest.
|
|
664
697
|
|
|
665
698
|
The rows are in `artifact_saves` (one for each save) and `artifacts` (one for
|
|
666
|
-
each version a save
|
|
699
|
+
each version a save contains), which migration `nisc.moss/5` makes. They are
|
|
667
700
|
read and written through three vex entries of moss's own that no route serves
|
|
668
701
|
(`src/artifactory/saves.ts`). What is in force for an artifact is its latest
|
|
669
702
|
version by `created_at`; every id moss gives is a uuid. A body is kept with
|
|
@@ -744,9 +777,9 @@ functions: (session) => [
|
|
|
744
777
|
refuses**, with the same sentences. Each artifact is checked beside what is
|
|
745
778
|
in force for the principal with the draft laid over, so a layout may be for
|
|
746
779
|
an action that is itself in the draft. A draft is one shell's, so what is
|
|
747
|
-
added to it is
|
|
748
|
-
those of any shell of the app. A new action or fragment
|
|
749
|
-
`generated.` id here, and keeps it when the draft is saved. An `id` names
|
|
780
|
+
added to it is checked against the components of that shell, where a save
|
|
781
|
+
is checked against those of any shell of the app. A new action or fragment
|
|
782
|
+
gets its `generated.` id here, and keeps it when the draft is saved. An `id` names
|
|
750
783
|
one in the draft, or one the principal saved: a new take of it, which stands
|
|
751
784
|
in for the saved one in this shell until the draft is saved or the take is
|
|
752
785
|
taken out. An add that marks a layout `use: true` takes the mark off the
|
|
@@ -758,13 +791,13 @@ functions: (session) => [
|
|
|
758
791
|
- **What the shell draws**: what is in the draft, then what `session.artifacts`
|
|
759
792
|
would draw. A drafted layout marked `use: true` is drawn in place of a saved
|
|
760
793
|
one that is marked for the same ref.
|
|
761
|
-
- **`list`** answers what the draft
|
|
794
|
+
- **`list`** answers what the draft contains, and **`remove`** takes one out of
|
|
762
795
|
it; what is under it is drawn again. **`discard`** empties it.
|
|
763
796
|
- **Each add or removal is a numbered step**, from 1. **`show(step)`** has the
|
|
764
797
|
shell show the draft as it was after that step, and `show(0)` none of it. A
|
|
765
798
|
add or a removal while an earlier step is shown goes on from that step: the
|
|
766
799
|
steps after it are dropped. The steps are the draft's and are saved nowhere.
|
|
767
|
-
- **`save`** is one save of what the draft
|
|
800
|
+
- **`save`** is one save of what the draft contains, as the principal's own and
|
|
768
801
|
under the ids it had, checked once more. The draft is then empty and the
|
|
769
802
|
shell keeps what it shows. An empty draft is refused.
|
|
770
803
|
- **Calls on one draft are taken in turn**: each starts from the draft as the
|
|
@@ -784,12 +817,15 @@ type NiscRuntime = {
|
|
|
784
817
|
db: MutationClient; // writes
|
|
785
818
|
cache?: CacheBackend; // defaults to vex's postgres cache on `pool`
|
|
786
819
|
vexConfig?: QueryEngineConfig['config']; // the query engine's settings (limits, read timeout); default vex's own
|
|
820
|
+
answerReadableRows?: boolean; // a write on the vex surfaces answers only the rows the caller may read; default false
|
|
821
|
+
checkMovedRows?: boolean; // refuse a write that moves a row out of the caller's update rule; default true
|
|
787
822
|
session: SessionVerifier | 'sessions' | 'dev-open'; // REQUIRED — no default
|
|
788
823
|
origins?: readonly string[]; // origins that are the app's own page, beside the host a request names (a proxy that rewrites `Host`)
|
|
789
824
|
migrations?: 'apply' | 'verify'; // the boot's ledgered run; default 'verify'
|
|
790
825
|
tables?: readonly Sequence[]; // the app's own table sequences, in that same run
|
|
791
826
|
shellIdleMs?: number; // idle shell eviction; default 30 min, `0` disables
|
|
792
827
|
artifactsUnusedMs?: number; // delete what a person generated once nobody has loaded it for this long; default never
|
|
828
|
+
artifactsUnusedSinceStart?: boolean; // count that time only since this server started; default false: time the app was down counts
|
|
793
829
|
anonymousShellMax?: number; // shells for nobody signed in alive at once; default 1,000, `Infinity` is no limit
|
|
794
830
|
endpointTimeoutMs?: number; // a server shell's endpoint call, and the build of a shell; default nova's, 30s
|
|
795
831
|
sessionRevalidateMs?: number; // live-socket re-verify; default 60s, `0` disables
|
|
@@ -811,7 +847,7 @@ the function form of `session`. The type is not exported by name.
|
|
|
811
847
|
`socketCompression` and `socketMaxMessageBytes` are settings of the Node
|
|
812
848
|
transport. The server reads them, once, and the socket it hands out
|
|
813
849
|
(`server.socket`) carries them to whichever transport is handed it. So they
|
|
814
|
-
|
|
850
|
+
apply wherever that socket is attached: under `serve`, `nisc start`, the dev
|
|
815
851
|
plugin (`nisc dev`), and a host of the app's own that calls
|
|
816
852
|
`attachSocket(httpServer, server.socket)`. No host says them again.
|
|
817
853
|
|
|
@@ -822,6 +858,19 @@ own reads and writes. The generation counter and a feature's own entries (the
|
|
|
822
858
|
integrations' registry) read the tables that are theirs off the database
|
|
823
859
|
whatever the list names, and know no other table.
|
|
824
860
|
|
|
861
|
+
`answerReadableRows` is vex's option of that name on the `/api/vex` surfaces
|
|
862
|
+
(vex DOCS, "Replay"). Without it a write answers every row it wrote, whole,
|
|
863
|
+
whatever the caller's read rules say. With it, a write answers only the rows
|
|
864
|
+
the caller's charter lets them read, and an entry whose role cannot read the
|
|
865
|
+
table it writes answers no row: a sign-in entry that deletes a one-time link
|
|
866
|
+
and reads who signs in from the deleted row stops working.
|
|
867
|
+
|
|
868
|
+
`checkMovedRows` is vex's option of that name, on the `/api/vex` surfaces and
|
|
869
|
+
`executeAs` (vex DOCS, "Replay"). An update that writes a column the caller's
|
|
870
|
+
update rule pins (`owner_id` under an `owner_id = me` rule) to a value the rule
|
|
871
|
+
does not allow is refused with 400 `scope_denied`, and nothing is written.
|
|
872
|
+
`checkMovedRows: false` lets such a write move the row, as moss did before.
|
|
873
|
+
|
|
825
874
|
`session` is required, deliberately — authentication is the one door that must
|
|
826
875
|
not default open, and it used to. Three answers: `'sessions'` uses moss's own
|
|
827
876
|
stored credential (below); `'dev-open'` trusts every well-formed token and says
|
|
@@ -842,7 +891,7 @@ asked about again, an identity record older than it is resolved again when it
|
|
|
842
891
|
is next read, and the generation pointer is polled
|
|
843
892
|
([Many processes](#many-processes)). `0` turns off all three, and so does
|
|
844
893
|
`Infinity` or any interval above 2^31 − 1 ms (24.8 days), the longest a timer
|
|
845
|
-
of Node's
|
|
894
|
+
of Node's can wait: a process then follows no `refresh`, `replaceActions` or
|
|
846
895
|
approval of an integration that another process made.
|
|
847
896
|
|
|
848
897
|
`operatorKey` is what a request under `/operator` presents as
|
|
@@ -866,10 +915,10 @@ Somebody signed in is served whatever the count is, and a shell one of the
|
|
|
866
915
|
manifest's pages builds for somebody signed in takes no place.
|
|
867
916
|
|
|
868
917
|
**What the limit is, exactly.** One count, for everybody with nobody signed
|
|
869
|
-
in, in one process. It bounds what that process
|
|
918
|
+
in, in one process. It bounds what that process keeps in memory for them, and
|
|
870
919
|
it does nothing else:
|
|
871
920
|
|
|
872
|
-
- It is not a limit for each visitor. Whoever
|
|
921
|
+
- It is not a limit for each visitor. Whoever takes the places keeps them:
|
|
873
922
|
one client that opens `anonymousShellMax` connections and keeps them open
|
|
874
923
|
has every place, and every other visitor with nobody signed in is sent
|
|
875
924
|
`at_capacity` until one of those closes. People who are signed in go on
|
|
@@ -883,20 +932,20 @@ it does nothing else:
|
|
|
883
932
|
close is like any other: the place is given back, a shell for nobody is
|
|
884
933
|
disposed, and a signed-in person's shell starts its idle time.
|
|
885
934
|
- It is counted by the process that takes the connection. A deployment of N
|
|
886
|
-
processes
|
|
935
|
+
processes allows up to N times the limit.
|
|
887
936
|
- Moss builds no limit for each address, because the address is not moss's
|
|
888
937
|
to know: behind a proxy every connection comes from the proxy, and which
|
|
889
938
|
header says where the visitor is, is the proxy's to say.
|
|
890
939
|
|
|
891
940
|
**A deployment that faces the internet** limits how many connections one
|
|
892
|
-
address may
|
|
941
|
+
address may keep open where the address is known: at its proxy or load balancer,
|
|
893
942
|
on the socket's path (`/socket`). With that in place, `anonymousShellMax` is
|
|
894
943
|
what it is sized for here, memory. What an app can do on its own: a first
|
|
895
944
|
screen for nobody that is a page which is not live opens no socket and takes
|
|
896
945
|
no place (`nisc build` says which pages are live, and why).
|
|
897
946
|
|
|
898
947
|
The default is from a measurement (2026-10-10, Node 24): lyceum's real boot,
|
|
899
|
-
2,000 connections for nobody opened through `server.socket` and
|
|
948
|
+
2,000 connections for nobody opened through `server.socket` and kept open, the heap
|
|
900
949
|
read after a forced collection before and after, with a transport that drops
|
|
901
950
|
what it is sent.
|
|
902
951
|
|
|
@@ -924,7 +973,7 @@ the row.
|
|
|
924
973
|
its own identity check and hands the token to the terminal (or sets it as
|
|
925
974
|
the browser's cookie, [`sessionCookies`](#sessioncookiespage-token-options)).
|
|
926
975
|
Expired rows are swept on every mint — no timer to run.
|
|
927
|
-
- `revokeAllFor` deletes every token a principal
|
|
976
|
+
- `revokeAllFor` deletes every token a principal has: signed out everywhere.
|
|
928
977
|
`session.revoke()` in a function calls it for the session's own principal;
|
|
929
978
|
this is for signing out somebody else (an owner removes a member).
|
|
930
979
|
No exported call deletes one token and leaves the principal's others.
|
|
@@ -944,10 +993,10 @@ the row.
|
|
|
944
993
|
in a function closes that principal's terminals and disposes their shell,
|
|
945
994
|
and forgets nothing: the app deletes its own credential where it signs
|
|
946
995
|
somebody out. An app that wants moss's stored sessions and a rule of its
|
|
947
|
-
own on top (a member who was removed,
|
|
996
|
+
own on top (a member who was removed, a suspended account) sets
|
|
948
997
|
`session: 'sessions'` and puts the rule where it belongs: `revokeAllFor`
|
|
949
998
|
when the member is removed, or `identity.resolve` answering
|
|
950
|
-
`{ roles: ['public'], scope: {} }` for somebody who may
|
|
999
|
+
`{ roles: ['public'], scope: {} }` for somebody who may be granted nothing.
|
|
951
1000
|
|
|
952
1001
|
```typescript
|
|
953
1002
|
// the app's own door: who they are is the app's to establish, then a session
|
|
@@ -1003,7 +1052,7 @@ reason as `fingerprint: why` — and nothing was applied. It asks on every run,
|
|
|
1003
1052
|
so a release that changes an entry and no table is checked too.
|
|
1004
1053
|
|
|
1005
1054
|
One kind of entry is said and not refused: one that already did not fit before
|
|
1006
|
-
the run and that the cache table already
|
|
1055
|
+
the run and that the cache table already has a copy of, exactly as it is. That
|
|
1007
1056
|
is an old fault, not this run's. A new or changed entry gets no such pass. A
|
|
1008
1057
|
copy is there where a release before 0.6.0 wrote it, or where the app writes
|
|
1009
1058
|
one itself for an engine of its own (`seedCache`). Moss writes none since
|
|
@@ -1088,7 +1137,7 @@ order: the manifest is read and frozen; who a token is is resolved
|
|
|
1088
1137
|
the tables are checked (migrated under `migrations: 'apply'`) and the data
|
|
1089
1138
|
module stands; the running manifest is
|
|
1090
1139
|
created, which is the boot check, and the data module is told to ask it for an
|
|
1091
|
-
entry (it compiles the ones it
|
|
1140
|
+
entry (it compiles the ones it keeps, and one vex cannot run refuses the boot);
|
|
1092
1141
|
identity; the server's own routes (the
|
|
1093
1142
|
authentication, `/catalog`, vex); the shell hosts, the app's and each page's;
|
|
1094
1143
|
what crosses processes; the features, each started with seams made for it; the
|
|
@@ -1096,22 +1145,22 @@ operator prefix; the app's reactions hear a write; the generation pointer is
|
|
|
1096
1145
|
watched; the socket.
|
|
1097
1146
|
A step that refuses is the boot's refusal.
|
|
1098
1147
|
|
|
1099
|
-
**Where the app's entries are
|
|
1100
|
-
(`src/artifactory/`), in memory, and nowhere else. It
|
|
1148
|
+
**Where the app's entries are kept.** In the running manifest
|
|
1149
|
+
(`src/artifactory/`), in memory, and nowhere else. It keeps the entries the
|
|
1101
1150
|
app shipped and each set handed over with `server.replaceEntries`, compiled as
|
|
1102
1151
|
vex replays them, and it is what the engine asks first: a request's
|
|
1103
1152
|
fingerprint, and the list of fingerprints a feature or the operator is told
|
|
1104
1153
|
of, resolve there. So what a fingerprint resolves to is what this process's
|
|
1105
1154
|
app ships, read from the build at every boot.
|
|
1106
1155
|
|
|
1107
|
-
What the running manifest does not
|
|
1156
|
+
What the running manifest does not have is asked of the cache table
|
|
1108
1157
|
(`vex_cache`, or the cache `runtime.cache` hands over). That table keeps what
|
|
1109
1158
|
vex wrote itself while the app runs: a query `session.answerIntent` wrote.
|
|
1110
1159
|
**Nothing is copied into it at boot, and a row in it that no request wrote is
|
|
1111
1160
|
not replayed.** Vex gives a query it writes the hash of the request it was
|
|
1112
1161
|
written for, and that is what moss asks of a row before it answers from it. A
|
|
1113
1162
|
release before 0.6.0 copied every entry of the app there at each boot, and a
|
|
1114
|
-
database that ran one still
|
|
1163
|
+
database that ran one still has those rows, which carry no such hash. Moss
|
|
1115
1164
|
answers from none of them and deletes none: an entry the app no longer ships
|
|
1116
1165
|
is refused (`cache_miss`). Two things an app may have leaned on are gone with
|
|
1117
1166
|
the copy:
|
|
@@ -1127,7 +1176,7 @@ the copy:
|
|
|
1127
1176
|
`action/<id>`. An app goes on writing an action's layout in its definition;
|
|
1128
1177
|
where a shell is built, moss moves it into the store, and the definition the
|
|
1129
1178
|
shell is handed names it by `{ ref: 'action/<id>' }`. A layout variant the
|
|
1130
|
-
person's roles
|
|
1179
|
+
person's roles are granted is what the store keeps under that name instead. An action
|
|
1131
1180
|
with no layout, or one whose `layout` is already the name of a stored layout,
|
|
1132
1181
|
is handed over as it is. Three things follow:
|
|
1133
1182
|
|
|
@@ -1138,7 +1187,7 @@ is handed over as it is. Three things follow:
|
|
|
1138
1187
|
endpoints and its triggers.
|
|
1139
1188
|
- **Code that reads an action's definition off its session's shell**
|
|
1140
1189
|
(`session.shell.getRuntime(id).definition`) finds it as it was written, with
|
|
1141
|
-
the layout in place: the one the store
|
|
1190
|
+
the layout in place: the one the store keeps now, so a variant or a change
|
|
1142
1191
|
shows. `server.actions()` answers the definitions as they were written too.
|
|
1143
1192
|
Only the whole shell (`unverifiedShell(session)`), which is nova's own,
|
|
1144
1193
|
shows `{ ref }`; there the layout is `shell.layoutStore.get('action/<id>')`.
|
|
@@ -1184,11 +1233,11 @@ The manifest does not parse — refusing to serve:
|
|
|
1184
1233
|
Each line is a place and what was expected there. An action, a fragment and a
|
|
1185
1234
|
layout (a layout variant's, a canvas's, the frame's, the layout store's) are
|
|
1186
1235
|
read by nova's schemas; an entry's `dsl` and `mutation` by vex's and its
|
|
1187
|
-
`mapping` by Prism's; `grammars` by strata's. Every other data field is
|
|
1236
|
+
`mapping` by Prism's; `grammars` by strata's. Every other data field is checked against
|
|
1188
1237
|
the shape `NiscApp` gives it, and a field `NiscApp` does not have is refused.
|
|
1189
|
-
A code seam is
|
|
1238
|
+
A code seam is checked to be a function. A component's contract
|
|
1190
1239
|
(`shell.components`) is the kit's own record and may carry more than moss
|
|
1191
|
-
names. The charter and `behaviors` are
|
|
1240
|
+
names. The charter and `behaviors` are checked to be objects; the charter is
|
|
1192
1241
|
verified by the check below and `behaviors` by vex when a policy is compiled.
|
|
1193
1242
|
|
|
1194
1243
|
**Then it is frozen**, every level of it, in place. Once `createServer` has
|
|
@@ -1222,7 +1271,8 @@ feature serves).
|
|
|
1222
1271
|
|
|
1223
1272
|
The socket is not a Hono route: `server.socket` is fed by the runtime's
|
|
1224
1273
|
transport (`/socket` under `serve` and `attachSocket`). Every request is
|
|
1225
|
-
identified once, from `Authorization: Bearer <token
|
|
1274
|
+
identified once, from `Authorization: Bearer <token>` (the scheme in any
|
|
1275
|
+
case; a header with no scheme is read whole as the token): a session token goes
|
|
1226
1276
|
through the `session` verifier (`401` when it does not resolve); a token
|
|
1227
1277
|
whose prefix a feature registered is that feature's to read (the integrations
|
|
1228
1278
|
read `ik_`, an integration key); no header is the anonymous principal. There
|
|
@@ -1262,7 +1312,7 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
|
|
|
1262
1312
|
where it cannot see (a role, an install): run the check boot runs over what
|
|
1263
1313
|
is in force (the charter, every entry's reach, the layout variants), drop
|
|
1264
1314
|
every per-principal memo and identity record, and have every living shell
|
|
1265
|
-
adopt: it is brought level with what its principal
|
|
1315
|
+
adopt: it is brought level with what its principal is granted now, in place
|
|
1266
1316
|
("A change is the server's", under `shells` below). Every living shell is
|
|
1267
1317
|
the one kept for each signed-in person, the one built for each connection
|
|
1268
1318
|
of nobody signed in, and the one a page built for each connection. It also
|
|
@@ -1303,7 +1353,7 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
|
|
|
1303
1353
|
is refused from then on, and a name a feature keeps is not the app's. The
|
|
1304
1354
|
entries in force are what the app shipped, then each set: an entry of a set
|
|
1305
1355
|
is replayed in place of one the app shipped under the same fingerprint, for
|
|
1306
|
-
as long as the set
|
|
1356
|
+
as long as the set contains it. Every entry is read by the schema the
|
|
1307
1357
|
manifest's entries are read by, compiled, and checked before the set is
|
|
1308
1358
|
taken: a write by vex's authoring lint, and the reach an entry declares by
|
|
1309
1359
|
the check boot runs. Refused, the promise rejects with what was found
|
|
@@ -1325,14 +1375,14 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
|
|
|
1325
1375
|
shows the build's again. **A layout:** `server.defaults(who).save([{ kind:
|
|
1326
1376
|
'layout', body: { ref: 'action/<id>', layout, use: true } }])` is drawn under
|
|
1327
1377
|
that action's ref unless its principal has a layout of their own in use or
|
|
1328
|
-
their roles
|
|
1378
|
+
their roles are granted a layout variant; `ref: 'frame'` and `ref: 'canvas/<id>'`
|
|
1329
1379
|
publish the layouts of the app's own shell. **An action or a fragment** is
|
|
1330
1380
|
given its id by whoever publishes it, as a shipped one has one: `save([{
|
|
1331
1381
|
kind: 'action', id: 'promo', body }])`; one without an id is refused, and so
|
|
1332
1382
|
is one under `generated.`. The charter grants it by that id, so a new id
|
|
1333
1383
|
needs a grant and one that is a shipped action's or fragment's replaces the
|
|
1334
1384
|
build's for everybody until it is reset. **A read** vex wrote is published
|
|
1335
|
-
under its fingerprint, `save([{ kind: 'read', id: '<fingerprint>' }])`, and is
|
|
1385
|
+
under its fingerprint, `save([{ kind: 'read', id: '<fingerprint>', body: undefined }])`, and is
|
|
1336
1386
|
answered to everybody after what the caller saved themselves; one under the
|
|
1337
1387
|
fingerprint of a shipped entry is refused. `publisher` is who the publish is
|
|
1338
1388
|
made by, kept with the save (`artifact_saves.created_by`); an empty one is
|
|
@@ -1351,9 +1401,9 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
|
|
|
1351
1401
|
calls are ones the publisher's roles grant, its reads ones they may replay,
|
|
1352
1402
|
no write), and then the whole as a manifest, as a set handed over is:
|
|
1353
1403
|
`Publish refused — actions call functions the app does not have, or that
|
|
1354
|
-
their holders’ charter does not grant:` lists
|
|
1355
|
-
|
|
1356
|
-
any more is left out with a line, said once for each read of the rows: a
|
|
1404
|
+
their holders’ charter does not grant:` lists whoever is granted an action
|
|
1405
|
+
whose call their roles do not grant. When the rows are read, the same
|
|
1406
|
+
again, and what does not pass any more is left out with a line, said once for each read of the rows: a
|
|
1357
1407
|
layout, an action or a fragment on its own where its own check refuses it
|
|
1358
1408
|
(`[moss] the action "…" published for everybody is left out: …`), and the
|
|
1359
1409
|
actions and fragments all together where the manifest refuses them (`[moss]
|
|
@@ -1361,7 +1411,7 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
|
|
|
1361
1411
|
…`). Once `checkFunctions` has read the app's functions, the rows are read
|
|
1362
1412
|
again against them: a published action calling a function a new build
|
|
1363
1413
|
dropped is left out, and the boot is not refused. When a shell is built, for
|
|
1364
|
-
that shell and that principal: a layout for an action they
|
|
1414
|
+
that shell and that principal: a layout for an action they are not granted is
|
|
1365
1415
|
not loaded, and a published fragment a shell cannot draw is left out of that
|
|
1366
1416
|
shell (`[moss] the fragment "…" published for everybody is left out of a
|
|
1367
1417
|
shell that cannot draw it: …`).
|
|
@@ -1372,16 +1422,16 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
|
|
|
1372
1422
|
A publish has every living shell adopt, as `refresh` does, and moves the
|
|
1373
1423
|
pointer, whether or not the rows can be read back: every other process on
|
|
1374
1424
|
the same database follows the pointer and reads them.
|
|
1375
|
-
- `catalogOf(principal): Promise<{ ids, hash }>` — what a principal
|
|
1425
|
+
- `catalogOf(principal): Promise<{ ids, hash }>` — what a principal is granted of the
|
|
1376
1426
|
actions in force: `{ ids, hash }`, the granted action ids sorted, with a
|
|
1377
1427
|
content-hash version token (equal hash, equal application). The principal is
|
|
1378
1428
|
resolved the way a request resolves it (the `identity` seam, or
|
|
1379
1429
|
`assignments`), so an integration's actions are there only where it is
|
|
1380
1430
|
installed. `null` is nobody signed in.
|
|
1381
|
-
There is no asking by a list of roles: what somebody
|
|
1431
|
+
There is no asking by a list of roles: what somebody is granted depends on who
|
|
1382
1432
|
they are resolved to be, installs included, and the server resolves it.
|
|
1383
1433
|
- `policyForRoles(roles): ScopePolicy` — what a set of roles may read and
|
|
1384
|
-
write: the vex policy a request by somebody
|
|
1434
|
+
write: the vex policy a request by somebody wearing exactly these roles is
|
|
1385
1435
|
served under, compiled from the charter and `behaviors` over every table the
|
|
1386
1436
|
database has. **One policy per role, merged** — a person may wear several (an
|
|
1387
1437
|
instructor who also trains here), and reach belongs to the role rather than
|
|
@@ -1391,8 +1441,9 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
|
|
|
1391
1441
|
- `charterReport(): VerifyReport` — the report `verifyCharter` gave this server:
|
|
1392
1442
|
boot's, then that of each change that passed. `{ errors, warnings,
|
|
1393
1443
|
perRole }`, over the universes boot resolved against. Boot and `refresh` read
|
|
1394
|
-
`errors
|
|
1395
|
-
|
|
1444
|
+
`errors`, and boot prints the `shape` warnings (a key the charter does not
|
|
1445
|
+
read, a string where a list belongs) and nothing else, so this is where a host reads
|
|
1446
|
+
it, to draw, log or stop a deploy on: `warnings` (an action no role grants, an
|
|
1396
1447
|
`allow` that matches nothing) and each role's closure `issues`. `errors` is
|
|
1397
1448
|
always empty here. A push whose target is a binding (`@event.payload`,
|
|
1398
1449
|
`$.target`) is listed among the `issues` as "not in the catalog", though it is
|
|
@@ -1400,23 +1451,24 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
|
|
|
1400
1451
|
- `invalidateIdentity(principal): boolean` — forget one principal's identity
|
|
1401
1452
|
record and reset every living shell of theirs (a role change): the one the
|
|
1402
1453
|
app keeps for them, and the one a page built for each connection of theirs.
|
|
1403
|
-
`false` = no record was
|
|
1454
|
+
`false` = no record was kept.
|
|
1404
1455
|
- `invalidateTag(tag): number` — forget every identity record wearing the
|
|
1405
1456
|
tag the app put on it (`IdentityRecord.tag`); answers how many. Then every
|
|
1406
1457
|
living shell adopts, as after `refresh` ("A change is the server's", under
|
|
1407
|
-
`shells` below): it is brought level with what its principal
|
|
1408
|
-
place, so a function or an action their new roles do not grant is no
|
|
1409
|
-
|
|
1458
|
+
`shells` below): it is brought level with what its principal is granted now,
|
|
1459
|
+
in place, so a function or an action their new roles do not grant is no
|
|
1460
|
+
longer in their shell. No shell is reset: what people were in the middle of stays. Every
|
|
1410
1461
|
living shell, not only those of the records forgotten: a record can be
|
|
1411
1462
|
dropped while its shell lives (past `runtime.identityMax`, or unread for
|
|
1412
1463
|
`runtime.identityIdleMs`), and no tag finds it then. So each call asks the app's
|
|
1413
1464
|
`identity` again for every signed-in person with a living shell whose
|
|
1414
|
-
record is not
|
|
1465
|
+
record is not kept.
|
|
1415
1466
|
- `identity(principal): Promise<IdentityRecord>` — who one principal is,
|
|
1416
1467
|
resolved the way a request resolves it: `{ roles, scope, installed? }`,
|
|
1417
1468
|
through the same cache the request path uses. `null` is nobody signed in.
|
|
1418
1469
|
With no `identity` seam the roles are the ones `assignments` names, and
|
|
1419
|
-
`scope` is empty.
|
|
1470
|
+
`scope` is empty. A principal it does not name as its own key is `public`,
|
|
1471
|
+
one called `toString` or `constructor` included.
|
|
1420
1472
|
- `identities?: { list(); meter() }` — the resident identity
|
|
1421
1473
|
roster (`{ principal, since, lastSeen }`) and what the cache costs
|
|
1422
1474
|
(`{ size, max, resolved, evicted, expired }`). Present only when the app
|
|
@@ -1513,17 +1565,17 @@ is live when something on it can still happen:
|
|
|
1513
1565
|
|
|
1514
1566
|
What can be pressed is read off the layout a screen is drawn with: a `{ ref }`
|
|
1515
1567
|
in it, the one an action's own layout is named by included, is read through
|
|
1516
|
-
to the layout the shell's store
|
|
1568
|
+
to the layout the shell's store keeps under it.
|
|
1517
1569
|
|
|
1518
1570
|
A read made while the action opened is **finished**: its answer is in the tree
|
|
1519
1571
|
(and listed in `drawnWith`). The app's own shell is always live for a signed-in
|
|
1520
1572
|
principal — it is the thing that is kept. nova supplies the facts
|
|
1521
1573
|
(`livenessOf`, `@niscorp/nova/reflect`); moss composes the verdict, because
|
|
1522
|
-
the running manifest
|
|
1574
|
+
the running manifest keeps the entries in force, by fingerprint
|
|
1523
1575
|
(`src/shells/snapshot.ts`; the function is not exported, its answer is
|
|
1524
1576
|
`live`, `why` and `drawnWith` on the snapshot). It reads that list and not
|
|
1525
|
-
the cache table, which can
|
|
1526
|
-
not
|
|
1577
|
+
the cache table, which can have more: a fingerprint the running manifest does
|
|
1578
|
+
not have (a query written by `answerIntent`) is the last line of the table.
|
|
1527
1579
|
|
|
1528
1580
|
When `live` is false the trees are the whole of the screen, and the terminal
|
|
1529
1581
|
opens no socket.
|
|
@@ -1562,26 +1614,26 @@ What it is handed is `DocumentConfig`, and what it answers is `DrawnDocument`.
|
|
|
1562
1614
|
the same node the effect reads it from. Values are escaped.
|
|
1563
1615
|
- **The page's `<head>` is its screen's own.** It is a node in a layout —
|
|
1564
1616
|
nova's `nova:head`, whose children (`nova:title`, `nova:meta`, `nova:link`,
|
|
1565
|
-
`nova:script`) are the elements a head
|
|
1617
|
+
`nova:script`) are the elements a head contains, their props the elements'
|
|
1566
1618
|
attributes. It is in the snapshot's trees like everything else on the screen,
|
|
1567
1619
|
so the elements are read off them and written into the template's `<head>`:
|
|
1568
1620
|
one takes the place of the tag that said the same thing, anything else is
|
|
1569
1621
|
added, and the rest of the head is left as the template has it. `head` in the
|
|
1570
1622
|
result is what was read (`{ elements, actions, refused }`); absent, the
|
|
1571
1623
|
screen has no head and the page went out with the template's. What a head may
|
|
1572
|
-
not
|
|
1624
|
+
not contain — something that runs, or styles — is left out and logged. In the
|
|
1573
1625
|
browser the terminal keeps the page's head on the same node as the screen
|
|
1574
1626
|
moves, and the template's own tags come back when it stops saying them.
|
|
1575
1627
|
- **`site`** is the address the site is served at. With it, every path's
|
|
1576
1628
|
document says its own canonical address (`<link rel="canonical">`, `og:url`).
|
|
1577
1629
|
Without it the template's is left as it is.
|
|
1578
|
-
- **`template`** must
|
|
1630
|
+
- **`template`** must contain the empty root (`root`, default
|
|
1579
1631
|
`<div id="root"></div>`). The screen goes inside it, the snapshot element
|
|
1580
1632
|
straight after. `root` is an empty element written as it stands in the
|
|
1581
1633
|
template, its opening tag and at once its closing tag: any element
|
|
1582
|
-
(`<main id="app"></main>`), not only a `div`. A template that does not
|
|
1634
|
+
(`<main id="app"></main>`), not only a `div`. A template that does not contain
|
|
1583
1635
|
the root, or a root that is not an empty element (an opening tag alone, one
|
|
1584
|
-
that
|
|
1636
|
+
that contains something, one closed in its own tag), has no place for a screen:
|
|
1585
1637
|
the page goes out undrawn (`drawn: false`), and the second case is logged.
|
|
1586
1638
|
- **`server`** is asked three things, and its type says so
|
|
1587
1639
|
(`DocumentConfig['server']`): `principalOf(token)`, `page(path)` and
|
|
@@ -1636,7 +1688,7 @@ paths (`server.executeAs` runs a read the app serves as a charter role), are the
|
|
|
1636
1688
|
caller's.
|
|
1637
1689
|
|
|
1638
1690
|
`renderDocument` is the one way a page is drawn, and its parts are not
|
|
1639
|
-
exported. It reads the session the browser
|
|
1691
|
+
exported. It reads the session the browser keeps off the request's cookie, and
|
|
1640
1692
|
it writes the snapshot into the page as a
|
|
1641
1693
|
`<script type="application/json" id="nisc-snapshot">` element with every `<`
|
|
1642
1694
|
(and U+2028/2029) escaped: a tree carries what people typed, and a path is
|
|
@@ -1659,7 +1711,7 @@ const files: ExportedDocument[] = await exportDocuments({ ...drawing, paths: ['/
|
|
|
1659
1711
|
The `Set-Cookie` values that keep `token` in the browser of the page at this
|
|
1660
1712
|
origin — or, for `null`, take it back. For a sign-in the app answers over HTTP
|
|
1661
1713
|
(a link redeemed, a provider's callback): set them on the response, and the
|
|
1662
|
-
page that follows is signed in having never
|
|
1714
|
+
page that follows is signed in having never had the token.
|
|
1663
1715
|
|
|
1664
1716
|
```typescript
|
|
1665
1717
|
server.get('/login', async (c) => {
|
|
@@ -1708,7 +1760,14 @@ and each one a page built for them, with the payload; every other process is
|
|
|
1708
1760
|
nudged on the same channel, without it. `false`: no shell of theirs lives
|
|
1709
1761
|
here.
|
|
1710
1762
|
|
|
1711
|
-
|
|
1763
|
+
**A channel is not a trusted lane.** The person's own terminal can publish
|
|
1764
|
+
any channel with any payload into their own shell (`{ type: 'publish',
|
|
1765
|
+
channel, payload }` on the socket), and inside the shell that cannot be told
|
|
1766
|
+
apart from `deliver`. An action must not treat what arrives on a channel as
|
|
1767
|
+
coming from the server: it re-reads what it needs under its own policy, as a
|
|
1768
|
+
reaction does.
|
|
1769
|
+
|
|
1770
|
+
Two rules keep this lane honest:
|
|
1712
1771
|
|
|
1713
1772
|
- **A reaction is told THAT a write landed, never what it wrote.** No rows.
|
|
1714
1773
|
A receiver that wants the data re-reads it under its own policy — a row
|
|
@@ -1773,7 +1832,7 @@ it answers `undefined`, nothing is minted.
|
|
|
1773
1832
|
`TIDE_DDL` are exported by `@niscorp/tide/postgres`. They were moss's, and do
|
|
1774
1833
|
what they did: see tide's [DOCS.md](../tide/DOCS.md), "The driver" and "The
|
|
1775
1834
|
Postgres store". `createTideStore(runtime.pool, { migrate: false })` takes the
|
|
1776
|
-
pool the runtime
|
|
1835
|
+
pool the runtime keeps, with `TIDE_SEQUENCE` in `runtime.tables`, and its tables
|
|
1777
1836
|
are ordinary tables to moss: migrated by `nisc migrate`, introspected,
|
|
1778
1837
|
grantable, and scoped by a behavior like any other.
|
|
1779
1838
|
|
|
@@ -1799,13 +1858,13 @@ them. The sequences are checked in the one ledgered run, before the feature
|
|
|
1799
1858
|
starts (migrated there under `migrations: 'apply'`), and `migrateTables`
|
|
1800
1859
|
applies them. A feature reads and writes those
|
|
1801
1860
|
tables through vex, as an app does, with entries of its own: they are seeded into a
|
|
1802
|
-
cache of their own,
|
|
1861
|
+
cache of their own, kept by an engine no route is handed, so `/api/vex`
|
|
1803
1862
|
answers `cache_miss` for one of them whatever the charter grants whoever asks,
|
|
1804
1863
|
and no surface lists it. They run under a policy that admits the tables the
|
|
1805
1864
|
feature named as its own and no other, and asks for no principal. An entry
|
|
1806
1865
|
that reads or writes any other table refuses the boot (`moss: the feature "…"
|
|
1807
1866
|
handed over an entry that reads or writes a table that is not its own: "…"`).
|
|
1808
|
-
What another table
|
|
1867
|
+
What another table contains, a feature reads as the app does: through the app's
|
|
1809
1868
|
entries, under the charter. A write by a feature tells the app's engine which
|
|
1810
1869
|
tables changed, so a reactive read over one of them answers again.
|
|
1811
1870
|
|
|
@@ -1819,7 +1878,7 @@ tables changed, so a reactive read over one of them answers again.
|
|
|
1819
1878
|
`server.invalidateIdentity`, `invalidateTag` and `nudge` publish after
|
|
1820
1879
|
applying locally: `invalidate-identity`, `invalidate-tag` and `nudge`. The
|
|
1821
1880
|
fourth, `adopt`, names a principal and tells a process to bring the shells
|
|
1822
|
-
it
|
|
1881
|
+
it keeps for them level with what they are granted now; moss publishes it when a
|
|
1823
1882
|
layout is saved for that principal (`session.artifacts`), and it says
|
|
1824
1883
|
nothing of what was saved. Best-effort:
|
|
1825
1884
|
each targets state that heals on its own clock. Unset, every path behaves as
|
|
@@ -1846,7 +1905,7 @@ tables changed, so a reactive read over one of them answers again.
|
|
|
1846
1905
|
that is unset), and when it has moved it reads again every set of actions
|
|
1847
1906
|
it has a loader for, drops what it had read of what is published for
|
|
1848
1907
|
everybody (the next shell it builds reads that again), runs the check
|
|
1849
|
-
boot runs over what it would then serve, drops what it derived (what each set of roles
|
|
1908
|
+
boot runs over what it would then serve, drops what it derived (what each set of roles is granted, the compiled
|
|
1850
1909
|
policies, the identity records) and has its living shells adopt.
|
|
1851
1910
|
**The pointer carries no set.** It says that something changed, and a
|
|
1852
1911
|
process learns what by reading rows. The only set that has a loader is the
|
|
@@ -1859,7 +1918,7 @@ tables changed, so a reactive read over one of them answers again.
|
|
|
1859
1918
|
what they derived and adopt again.
|
|
1860
1919
|
The row is read and moved through vex, by two
|
|
1861
1920
|
entries of moss's own that no route serves (`src/data/own-entries.ts`);
|
|
1862
|
-
`src/artifactory/generation.ts`
|
|
1921
|
+
`src/artifactory/generation.ts` keeps the clock and no SQL. A move is a compare
|
|
1863
1922
|
and a set: the next number is written where the counter is still what was
|
|
1864
1923
|
read, and read again where it is not. A move a process could not follow is
|
|
1865
1924
|
tried again at every poll until it is followed, and logged when that is
|
|
@@ -1868,13 +1927,13 @@ tables changed, so a reactive read over one of them answers again.
|
|
|
1868
1927
|
has moved on or the reload fails another way, and once when it is followed
|
|
1869
1928
|
(`followed the generation pointer to 4, after 12 looks that failed`). A
|
|
1870
1929
|
reload that fails the same way for an hour is one line, not sixty.
|
|
1871
|
-
- The identity cache — what
|
|
1930
|
+
- The identity cache — what keeps the records `app.identity` resolves. It is
|
|
1872
1931
|
the server's own (`src/identity/cache.ts`) and is not exported. Its limits
|
|
1873
1932
|
are `runtime.identityMax` (default 10,000) and `runtime.identityIdleMs`
|
|
1874
1933
|
(default 30 minutes). At `identityMax` the least recently read record is
|
|
1875
1934
|
dropped to make room, and whoever it was is resolved again on their next
|
|
1876
1935
|
request. A record is forgotten with `server.invalidateIdentity`,
|
|
1877
|
-
`invalidateTag` and `refresh`, and what is
|
|
1936
|
+
`invalidateTag` and `refresh`, and what is kept is read through
|
|
1878
1937
|
`server.identities`.
|
|
1879
1938
|
|
|
1880
1939
|
### Telemetry
|
|
@@ -1892,13 +1951,13 @@ with `integrations/` and whose `hasPrincipal` is `false`. The generation
|
|
|
1892
1951
|
counter's poll emits none. A `socket.upgrade` is `ok` (admitted), `refused` (the token
|
|
1893
1952
|
offered is nobody's, or no place is left for a shell for nobody) or
|
|
1894
1953
|
`error` (the session could not be opened: the verifier
|
|
1895
|
-
threw, what somebody
|
|
1954
|
+
threw, what somebody is granted could not be asked, their shell could not be built).
|
|
1896
1955
|
A `socket.close` span runs from the upgrade to the close.
|
|
1897
1956
|
`emit` is never awaited, and a sink that throws costs the caller nothing: the
|
|
1898
1957
|
throw is caught where the span is emitted, and logged.
|
|
1899
1958
|
|
|
1900
1959
|
`refused` is a no the server gave (a policy, a limit, an integration that is
|
|
1901
|
-
not installed): an outcome, and not a fault. `attributes`
|
|
1960
|
+
not installed): an outcome, and not a fault. `attributes` contains identifiers
|
|
1902
1961
|
and measurements (a fingerprint, a count, a status) and never a payload, a
|
|
1903
1962
|
row or who a principal is: a principal is there only as `hasPrincipal`. Moss
|
|
1904
1963
|
sets none of `traceId`, `spanId` and `parentSpanId`.
|
|
@@ -1913,7 +1972,7 @@ const telemetry: Telemetry = { emit: (span) => void spans.push(span) };
|
|
|
1913
1972
|
|
|
1914
1973
|
### Resolution
|
|
1915
1974
|
|
|
1916
|
-
Who somebody is, what they
|
|
1975
|
+
Who somebody is, what they are granted and what they may read and write are asked of
|
|
1917
1976
|
the server, which resolves a principal the way a request does (the `identity`
|
|
1918
1977
|
seam, or `assignments`): `(await server.identity(principal)).roles`,
|
|
1919
1978
|
`server.catalogOf(principal)`, `server.policyForRoles(roles)`. Nothing is
|
|
@@ -1933,7 +1992,7 @@ app that resolves people through `identity`.
|
|
|
1933
1992
|
- An entry that declares a `reach` (vex) is served under the same roles'
|
|
1934
1993
|
grants recompiled at that named profile. The vex surfaces and `executeAs` do
|
|
1935
1994
|
it themselves; it narrows rows, never widens verbs.
|
|
1936
|
-
- A layout variant a set of roles
|
|
1995
|
+
- A layout variant a set of roles is granted (ring 2) is put in place of its
|
|
1937
1996
|
action's layout where a shell is built, in the shell's layout store.
|
|
1938
1997
|
Nothing answers the variants by themselves.
|
|
1939
1998
|
- `verifyApp(app, grants)` — the check boot runs, for an app
|
|
@@ -1945,7 +2004,8 @@ app that resolves people through `identity`.
|
|
|
1945
2004
|
report is `{ errors, said, charter }`: `errors` is `{ check, detail }[]`,
|
|
1946
2005
|
`check` one of `'actions'` (a definition nova's schema does not read),
|
|
1947
2006
|
`'charter'`, `'reach'` and `'variants'`; `said` is what a boot only says (a
|
|
1948
|
-
chain of steps that never ends
|
|
2007
|
+
chain of steps that never ends, a role that allows every function, and the
|
|
2008
|
+
charter's `shape` warnings), and `charter` is the charter engine's whole
|
|
1949
2009
|
report. A boot refuses on `errors`. A running server answers for what is in
|
|
1950
2010
|
force with `server.charterReport()`. It verifies and does nothing else: what
|
|
1951
2011
|
it is handed is not read by the manifest's schema and is not frozen.
|
|
@@ -1976,7 +2036,7 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
|
|
|
1976
2036
|
is not exported). It is handed no manifest and no
|
|
1977
2037
|
runtime, but a typed object of what it needs: one function that answers what
|
|
1978
2038
|
a principal's shell is made of (who they are, the action definitions they
|
|
1979
|
-
|
|
2039
|
+
are granted, the canvases and the frame, each naming its layout in the layout
|
|
1980
2040
|
store, the layout store's seed with those layouts in it (for an action the
|
|
1981
2041
|
published one over the build's, their roles' layout variant over that, and
|
|
1982
2042
|
over it the layout of their own they marked in use), the
|
|
@@ -1989,11 +2049,11 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
|
|
|
1989
2049
|
reach a shell through that one answer, and the server's wiring reads none
|
|
1990
2050
|
of them off the app. For an entry that is what a shell is told of the reads
|
|
1991
2051
|
on its screens. What a read replays the engine asks the running manifest
|
|
1992
|
-
for too (see "Where the app's entries are
|
|
2052
|
+
for too (see "Where the app's entries are kept", under `createServer`).
|
|
1993
2053
|
A kept shell may sit unattached for
|
|
1994
2054
|
`runtime.shellIdleMs` (default 30 minutes; `0` disables the sweep). A shell
|
|
1995
2055
|
that is not kept (nobody signed in; any shell of a page's host) ends when
|
|
1996
|
-
its last terminal leaves, and the host
|
|
2056
|
+
its last terminal leaves, and the host keeps nothing of a shell that has
|
|
1997
2057
|
ended.
|
|
1998
2058
|
- `session(token, principal, options?)` — `options = { seed?, inputs? }`;
|
|
1999
2059
|
`snapshot` is described under [The document](#the-document), and what it
|
|
@@ -2011,13 +2071,13 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
|
|
|
2011
2071
|
so that a change can reach it. The socket ends it when the connection
|
|
2012
2072
|
closes. Code that opens one in process and attaches nothing ends it
|
|
2013
2073
|
itself, with `session.detach(connection)` (any connection: none was
|
|
2014
|
-
attached); until then the host
|
|
2074
|
+
attached); until then the host keeps the shell.
|
|
2015
2075
|
- A host has no `adopt` and no `stop`. Each was a second way, for one
|
|
2016
2076
|
host, to something a server does for all of them at once.
|
|
2017
2077
|
**A change is the server's.** When what the app consists of changes
|
|
2018
2078
|
(`server.refresh()`, `server.replaceActions()`, `server.replaceEntries()`, an integration approved
|
|
2019
2079
|
or removed, a change another process made), every living shell of every
|
|
2020
|
-
host adopts (a layout somebody saved for themselves is adopted by the shells of that principal alone): it is brought level with what its principal
|
|
2080
|
+
host adopts (a layout somebody saved for themselves is adopted by the shells of that principal alone): it is brought level with what its principal is granted now, in
|
|
2021
2081
|
place. Every living shell: the ones a host keeps, and the ones it built
|
|
2022
2082
|
for one connection, which for the app's host is each visitor's and for a
|
|
2023
2083
|
page's host is everybody's. Definitions that arrived or changed are
|
|
@@ -2035,13 +2095,13 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
|
|
|
2035
2095
|
it. The canvases a shell's manifest declares, and what is mounted on any
|
|
2036
2096
|
canvas, are the shell's own state and are not taken again: a reset builds
|
|
2037
2097
|
that afresh. A canvas the manifest does not declare, that a layout in
|
|
2038
|
-
force
|
|
2039
|
-
it, once no layout
|
|
2040
|
-
shell that cannot adopt is logged and keeps what it
|
|
2098
|
+
force had a slot for, is taken out by an adopt, with what is mounted on
|
|
2099
|
+
it, once no layout has the slot. A
|
|
2100
|
+
shell that cannot adopt is logged and keeps what it had; the rest go on.
|
|
2041
2101
|
Each shell adopts on its own: one whose principal is never answered (an
|
|
2042
|
-
`identity` that hangs for them)
|
|
2102
|
+
`identity` that hangs for them) delays no other. So a change asks about
|
|
2043
2103
|
every living shell in the same moment, and an app's `identity` runs at
|
|
2044
|
-
once for every signed-in principal whose record is not
|
|
2104
|
+
once for every signed-in principal whose record is not kept.
|
|
2045
2105
|
A shell whose build was under way adopts when it lands, and so does one a
|
|
2046
2106
|
reset was replacing; no change waits for a build, or for another change.
|
|
2047
2107
|
One built for the length of a `snapshot` is read and ended, and adopts
|
|
@@ -2055,7 +2115,9 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
|
|
|
2055
2115
|
it built for each of their connections.) `false` = they have no living
|
|
2056
2116
|
shell in this host; nothing is built. This host, in this process: it
|
|
2057
2117
|
reaches no page's shell and no other process. To tell somebody's screens
|
|
2058
|
-
that something changed, wherever they live, a server calls `nudge`.
|
|
2118
|
+
that something changed, wherever they live, a server calls `nudge`. The
|
|
2119
|
+
person's own terminal can publish the same channel with any payload, so
|
|
2120
|
+
what arrives on a channel is a ping, not the server's word.
|
|
2059
2121
|
- `list()` — every durable shell alive right now, each as
|
|
2060
2122
|
`{ principal, connections, since, idleSince, canvases }`. moss owns the map,
|
|
2061
2123
|
so moss enumerates it; an app keeping its own note beside it can only drift.
|
|
@@ -2070,7 +2132,7 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
|
|
|
2070
2132
|
Every living shell of theirs on this host: the one it keeps for them, or,
|
|
2071
2133
|
on a host that keeps none (a page's), the one built for each of their
|
|
2072
2134
|
connections, each replaced for itself.
|
|
2073
|
-
`false` = they
|
|
2135
|
+
`false` = they have no shell, which is an answer, not an error. The
|
|
2074
2136
|
replacement is built from what the shell was opened with (for a page's,
|
|
2075
2137
|
the inputs of its path and its id seed), and a shell's resets run one
|
|
2076
2138
|
after another. A reset that arrives while another waits for its turn is
|
|
@@ -2087,9 +2149,9 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
|
|
|
2087
2149
|
remote clients ride `attach`/`dispatch`. Nine members of `shell` throw, as
|
|
2088
2150
|
on [`FunctionSession`](#functionsession): the whole shell is
|
|
2089
2151
|
`unverifiedShell(session)`. `shell` is a **getter** — `reset`
|
|
2090
|
-
replaces the shell under a session already
|
|
2152
|
+
replaces the shell under a session already handed out, so a snapshot of the field
|
|
2091
2153
|
would go on addressing the disposed one.
|
|
2092
|
-
`dispatch(canvas, event)`
|
|
2154
|
+
`dispatch(canvas, event)` checks what a terminal sent to the shell: the
|
|
2093
2155
|
canvas must be one the shell has, an `origin` the event names must be an
|
|
2094
2156
|
instance on that canvas (with none, the canvas's active instance is
|
|
2095
2157
|
stamped), and the event must parse as one of nova's (`NovaEventSchema`:
|
|
@@ -2138,7 +2200,7 @@ server.nudge('usr_ada', 'notes-changed');
|
|
|
2138
2200
|
transport: `server.socket(url, connection)`. `server.socket.stop()` ends
|
|
2139
2201
|
revalidation (the timer is unref'd, so a plain process needn't call it).
|
|
2140
2202
|
`createServer` builds it (`src/socket/`), handed who a token is, what
|
|
2141
|
-
somebody
|
|
2203
|
+
somebody is granted, and where a session comes from for the app and for each
|
|
2142
2204
|
page. Neither its factory nor its type is exported by name: the type is
|
|
2143
2205
|
`MossServer['socket']`.
|
|
2144
2206
|
- **Identity is asked twice.** At upgrade, and then every
|
|
@@ -2147,15 +2209,28 @@ server.nudge('usr_ada', 'notes-changed');
|
|
|
2147
2209
|
somebody else — gets an `invalid_token` error frame and a `4401` close, which
|
|
2148
2210
|
is the recovery the terminal already performs: drop the token, reconnect
|
|
2149
2211
|
anonymous, land on the served lock screen.
|
|
2150
|
-
- Anonymous connections are never revalidated: nothing they
|
|
2212
|
+
- Anonymous connections are never revalidated: nothing they have can expire.
|
|
2151
2213
|
- A verifier that **throws** is a fault, not a sign-out — the connection is
|
|
2152
2214
|
left alone and asked again next pass, so a database blip cannot become an
|
|
2153
2215
|
outage. Only an explicit `null` (or a changed principal) closes. That it
|
|
2154
2216
|
threw is logged, once for a pass: how many connections could not be asked
|
|
2155
2217
|
about, and the first error.
|
|
2156
|
-
- One pass at a time: a pass asks
|
|
2157
|
-
|
|
2158
|
-
|
|
2218
|
+
- One pass at a time: a pass asks the verifier once for each token, every
|
|
2219
|
+
token at the same moment, so connections that present one token share one
|
|
2220
|
+
call, and a revoked token's socket closes within one `sessionRevalidateMs`
|
|
2221
|
+
plus the time the verifier takes to answer, however many connections there
|
|
2222
|
+
are. The most the verifier is called is once for each distinct token every
|
|
2223
|
+
`sessionRevalidateMs`, and the calls of a pass arrive together at its
|
|
2224
|
+
start: with 200 tokens, 200 calls at once each interval. A verifier with a
|
|
2225
|
+
strict limit on calls at once queues them itself; with
|
|
2226
|
+
`session: 'sessions'` they are 200 queries on the pool at once, ahead of
|
|
2227
|
+
requests that arrive in that moment. A pass waits for the answers until
|
|
2228
|
+
the next pass is due; an answer that comes later is acted on when it comes
|
|
2229
|
+
(a `null` closes), and those connections are not asked about again until
|
|
2230
|
+
it has come. A pass that came due while another was still waiting starts
|
|
2231
|
+
as soon as that one ends. A slow verifier is not asked more the slower it
|
|
2232
|
+
gets. A verifier that never answers for one token leaves only that token's
|
|
2233
|
+
connections unchecked, and every other is still asked.
|
|
2159
2234
|
- Without this the socket was the asymmetry: the HTTP surfaces re-ask on
|
|
2160
2235
|
every request, so an expired credential left the socket open and rendering
|
|
2161
2236
|
while every endpoint the server shell called came back 401 — a live
|
|
@@ -2166,7 +2241,7 @@ server.nudge('usr_ada', 'notes-changed');
|
|
|
2166
2241
|
catalog asked, its shell built) is not attached to a shell, so a kept shell
|
|
2167
2242
|
idles and one built for that connection alone is disposed. The type also
|
|
2168
2243
|
has `upgrade` (below) and `seal`. `seal` is set by the socket, on a
|
|
2169
|
-
connection whose browser
|
|
2244
|
+
connection whose browser has a seal: a transport leaves it out.
|
|
2170
2245
|
- `ServerMessage` (`@niscorp/moss/protocol`) — what the server sends: `hello | catalog | frame | render |
|
|
2171
2246
|
render-delta | session | pong | error`.
|
|
2172
2247
|
- What a terminal sends is `event | publish | resync | reset | back | popTo | ping`,
|
|
@@ -2203,7 +2278,7 @@ server.nudge('usr_ada', 'notes-changed');
|
|
|
2203
2278
|
protocol-level, not app-level — no action declares it and no charter grants
|
|
2204
2279
|
it — and it is answered by the frames it produces, not by an envelope of its
|
|
2205
2280
|
own. Any terminal may send it, signed in or not, and each one that is acted
|
|
2206
|
-
on is a whole build: who somebody is, what they
|
|
2281
|
+
on is a whole build: who somebody is, what they are granted, and the app's
|
|
2207
2282
|
`inputs`, `phrases`, `functions` and `seeds`. Resets that arrive while one
|
|
2208
2283
|
waits for its turn are answered by it (`reset(principal)`, under `shells`),
|
|
2209
2284
|
so a burst costs two builds at most. Nothing limits how often: a terminal
|
|
@@ -2232,7 +2307,7 @@ server.nudge('usr_ada', 'notes-changed');
|
|
|
2232
2307
|
- `4503`: the server is serving as many terminals with nobody signed in as
|
|
2233
2308
|
`runtime.anonymousShellMax` allows, and built no shell for this one. An
|
|
2234
2309
|
`at_capacity` error frame, then the close. Not a recovery: the terminal
|
|
2235
|
-
keeps what it
|
|
2310
|
+
keeps what it has and reconnects with its usual backoff, which grows
|
|
2236
2311
|
for as long as it is refused.
|
|
2237
2312
|
- `4426`: the two ends speak protocols the other cannot (below).
|
|
2238
2313
|
- `error` codes: `invalid_token`, `session_failed`, `at_capacity`,
|
|
@@ -2248,7 +2323,7 @@ server.nudge('usr_ada', 'notes-changed');
|
|
|
2248
2323
|
- **Who a terminal is** is decided on the upgrade request, from a header of
|
|
2249
2324
|
it — never from its address, which is what every proxy on the way writes
|
|
2250
2325
|
into its log. A terminal offers the subprotocol `nisc`, and beside it its
|
|
2251
|
-
token when it
|
|
2326
|
+
token when it has one: `offerToken(token | null)` returns the list to
|
|
2252
2327
|
construct the socket with (`new WebSocket(url, offerToken(token))`), and the
|
|
2253
2328
|
server answers `nisc`. A token in the address (`?token=`) is not read. A
|
|
2254
2329
|
transport hands the offer over as `connection.upgrade.offered`
|
|
@@ -2257,14 +2332,16 @@ server.nudge('usr_ada', 'notes-changed');
|
|
|
2257
2332
|
- **A browser on the app's own page** is who its session cookie says
|
|
2258
2333
|
([`sessionCookies`](#sessioncookiespage-token-options)). The cookie is read
|
|
2259
2334
|
only when the upgrade's `Origin` is the host it was addressed to, or one
|
|
2260
|
-
`runtime.origins` lists.
|
|
2261
|
-
|
|
2335
|
+
`runtime.origins` lists. A `Host` that writes out the scheme's own port
|
|
2336
|
+
(`app.example.com:443` for `https://app.example.com`, `:80` for `http`)
|
|
2337
|
+
names the same host. (Behind a proxy that rewrites `Host` and with
|
|
2338
|
+
nothing listed, no page is the app's own: terminals keep their own tokens,
|
|
2262
2339
|
as before, and moss says so once in the log.) A token such a page offers is who it is and is
|
|
2263
2340
|
moved into the cookie by the answer to the upgrade; one that no longer
|
|
2264
2341
|
resolves is nobody (served, not refused) and is taken back. `?key=` names
|
|
2265
2342
|
which of the browser's sessions the terminal is — a seat; the cookie is named
|
|
2266
2343
|
by it. `?leave=1` is a terminal that was signed out: it is nobody whatever
|
|
2267
|
-
its browser
|
|
2344
|
+
its browser has, and the cookie is taken back. A transport passes what the
|
|
2268
2345
|
request carried as `connection.upgrade` — `{ offered, origin, host, cookie }`
|
|
2269
2346
|
— and, when it has not answered the request yet, `answer(cookies)`: moss
|
|
2270
2347
|
calls it once who is asking is decided, with the `Set-Cookie` values to
|
|
@@ -2354,12 +2431,12 @@ through the object form — when connection count matters more than bandwidth.
|
|
|
2354
2431
|
An object is handed to `ws` verbatim; see its `perMessageDeflate` options.
|
|
2355
2432
|
|
|
2356
2433
|
The setting is the Node transport's, and the server's socket carries it there
|
|
2357
|
-
from the runtime: it
|
|
2434
|
+
from the runtime: it applies under `serve`, `nisc start`, the dev plugin, and a
|
|
2358
2435
|
host that attaches `server.socket` itself.
|
|
2359
2436
|
|
|
2360
2437
|
#### Frame deltas — `runtime.shellFrameDelta`, default **off**
|
|
2361
2438
|
|
|
2362
|
-
A changed canvas, described against the frame that connection already
|
|
2439
|
+
A changed canvas, described against the frame that connection already has:
|
|
2363
2440
|
copy runs from the old frame plus literal inserts, checksummed.
|
|
2364
2441
|
|
|
2365
2442
|
```typescript
|
|
@@ -2379,7 +2456,7 @@ the same shell, in the same pass. The two kinds of connection coexist.
|
|
|
2379
2456
|
**A canvas whose frame is over 64 KB is always sent whole.** Comparing two
|
|
2380
2457
|
frames costs the server in proportion to their size, not to what changed, and
|
|
2381
2458
|
it does that work on the thread every session shares — about 7 ms at 64 KB, a
|
|
2382
|
-
second at 2.7 MB. So when the frame a terminal
|
|
2459
|
+
second at 2.7 MB. So when the frame a terminal has, or the one replacing it,
|
|
2383
2460
|
is longer than 64 KB, the server does not compare them. It is not a setting.
|
|
2384
2461
|
|
|
2385
2462
|
What it buys, measured on Lyra:
|
|
@@ -2443,7 +2520,7 @@ Correctness, which matters more than the saving:
|
|
|
2443
2520
|
first; this is the catch-all. `owned` (default: moss's own prefixes) names
|
|
2444
2521
|
what is never a page — an unknown path under one is a 404, not a screen. So is
|
|
2445
2522
|
a **missing file**: a name with an extension that is neither a file in `dist`
|
|
2446
|
-
nor a page of the manifest is answered 404 (a browser
|
|
2523
|
+
nor a page of the manifest is answered 404 (a browser keeping a page from
|
|
2447
2524
|
before a deploy asks for its script by the old name, and needs "gone" back,
|
|
2448
2525
|
not a document). A page's own path may have a dot in it (`/docs/v1.2`).
|
|
2449
2526
|
What a browser may keep of these files, and compressing what goes out, is not
|
|
@@ -2486,7 +2563,12 @@ Requires the optional `vite` peer.
|
|
|
2486
2563
|
(`renderDocument`); `MOSS_PATHS` go to the app server; the rest is vite's.
|
|
2487
2564
|
An edit under a watched path re-boots the whole app and reloads the page;
|
|
2488
2565
|
the outgoing server answers until the new one is up, and a failed re-boot
|
|
2489
|
-
keeps it.
|
|
2566
|
+
keeps it. What the charter does not read as written (its `shape` warnings
|
|
2567
|
+
in `server.charterReport()`, such as a misspelt `denny`) is shown over the
|
|
2568
|
+
page on vite's error overlay each time a browser connects, one line for
|
|
2569
|
+
each; the app runs under it. While the overlay is open, it covers the page,
|
|
2570
|
+
and vite turns the next live update into a full reload. An app whose
|
|
2571
|
+
charter has no `shape` warning never sees it. The connections of an app that is let go are closed (`1001`), so
|
|
2490
2572
|
a terminal that is not a page connects again, to the app that is booted.
|
|
2491
2573
|
- `options.app(load): Promise<DevApp>` — stand the app up. `load` is vite's
|
|
2492
2574
|
`ssrLoadModule`. `DevApp = { server, close?, draw?, htmlAttributes?,
|
|
@@ -2498,9 +2580,15 @@ Requires the optional `vite` peer.
|
|
|
2498
2580
|
end of the request's socket is loopback (`127.0.0.0/8`, `::1`, or either
|
|
2499
2581
|
written as an IPv4-mapped IPv6 address). Any other request is answered
|
|
2500
2582
|
`403` with a sentence that says why, and the app is not asked. What a
|
|
2501
|
-
header says of where a request came from (`X-Forwarded-For`)
|
|
2502
|
-
behind a proxy on the same machine every request is the proxy's,
|
|
2503
|
-
this machine's.
|
|
2583
|
+
header says of where a request came from (`X-Forwarded-For`) decides
|
|
2584
|
+
nothing; behind a proxy on the same machine every request is the proxy's,
|
|
2585
|
+
and is this machine's. A tunnel (ngrok, cloudflared, a dev tunnel) is such
|
|
2586
|
+
a proxy: anybody who has its address signs in as anybody. When
|
|
2587
|
+
`X-Forwarded-For`, `X-Real-IP` or `Forwarded: for=` names an address other
|
|
2588
|
+
than this machine, the sign-in is answered (`302`, with the session) and
|
|
2589
|
+
the dev log says so. A proxy that names no address (`Forwarded:
|
|
2590
|
+
for=unknown`, or a hidden name such as `for=_hidden`) gets the same line in
|
|
2591
|
+
the log; nothing is refused for it.
|
|
2504
2592
|
- `signInFromNetwork?: boolean` (default `false`) answers the sign-in to
|
|
2505
2593
|
every device that can reach the dev server, for trying a signed-in screen
|
|
2506
2594
|
on a phone. It hands out a session for whoever the address names: with it
|
|
@@ -2607,7 +2695,7 @@ vocabulary, and the app that has it defines it.
|
|
|
2607
2695
|
|
|
2608
2696
|
`check` and `prepare` are handed, as `bundle` (`ExtensionContext`), what moss
|
|
2609
2697
|
knows of the bundle: `integration` (its id), `url` (where its service
|
|
2610
|
-
lives), `actions` (its action definitions, each already
|
|
2698
|
+
lives), `actions` (its action definitions, each already checked against its
|
|
2611
2699
|
namespace, its endpoints and the kit), `fingerprints` (the ones the app
|
|
2612
2700
|
serves), and `layoutMisfits(layout)` (each place a layout does not fit the
|
|
2613
2701
|
app's kit, for a vocabulary that lets a bundle carry one).
|
|
@@ -2616,7 +2704,7 @@ vocabulary, and the app that has it defines it.
|
|
|
2616
2704
|
"console.log(require('node:crypto').randomBytes(32).toString('base64'))"`).
|
|
2617
2705
|
With none, a keypair is made when the feature starts and kept nowhere, so
|
|
2618
2706
|
each boot and each process has its own. Give one where an integration's
|
|
2619
|
-
service
|
|
2707
|
+
service keeps the public half in its environment, or where a deployment
|
|
2620
2708
|
runs more than one process: the same seed is the same key everywhere. It is
|
|
2621
2709
|
this feature's setting and no other feature is handed it. One that decodes
|
|
2622
2710
|
to fewer than 32 bytes refuses the boot.
|
|
@@ -2646,14 +2734,14 @@ that:
|
|
|
2646
2734
|
- `listIntegrations(): Promise<RegisteredIntegration<Extension>[]>` — every
|
|
2647
2735
|
registered integration, in the order of the ids: `{ id, status, url,
|
|
2648
2736
|
extension }`. `status` is `'pending'` or `'approved'`; `extension` is what
|
|
2649
|
-
the row
|
|
2737
|
+
the row stores, read by the app's schema and so typed by it (`undefined`: the
|
|
2650
2738
|
bundle carried none, the app supplied no schema, or the schema no longer
|
|
2651
2739
|
reads what was stored, which is logged with the integration's id). An app
|
|
2652
2740
|
builds its placements, its listing and anything else from this.
|
|
2653
2741
|
- `callIntegration(id, path, { principal, method?, body?, scope? }):
|
|
2654
2742
|
Promise<Response>` — call an installed integration when
|
|
2655
2743
|
nobody is driving; throws unless it is approved and installed for the
|
|
2656
|
-
principal's tenant. It is not
|
|
2744
|
+
principal's tenant. It is not checked against the integration's reach: an app calls
|
|
2657
2745
|
an endpoint its own vocabulary names (a preview, a page it mounts on a route
|
|
2658
2746
|
of its own) with this. `principal` is who the call is made for, and who the
|
|
2659
2747
|
assertion names. `method` defaults to `POST`; `body` is sent as JSON;
|
|
@@ -2674,7 +2762,7 @@ for everybody, and an empty list is none.
|
|
|
2674
2762
|
The rule that reads it is this feature's (an
|
|
2675
2763
|
`ext.<audience>.<integration>.<name>` action is there for somebody only where
|
|
2676
2764
|
that integration is in their list), and it is laid when the feature starts:
|
|
2677
|
-
an app that names no feature has no such rule, and
|
|
2765
|
+
an app that names no feature has no such rule, and has an `ext.…` action
|
|
2678
2766
|
of its own wherever the charter grants it.
|
|
2679
2767
|
|
|
2680
2768
|
What the feature serves once it is started:
|
|
@@ -2687,10 +2775,10 @@ What the feature serves once it is started:
|
|
|
2687
2775
|
|
|
2688
2776
|
A bearer token with the `ik_` prefix is an integration key: it is resolved to
|
|
2689
2777
|
the integration it was issued to and, through `integrationActor`, to a
|
|
2690
|
-
principal (`401` unknown key, `403` no actor). No two integrations
|
|
2778
|
+
principal (`401` unknown key, `403` no actor). No two integrations have the
|
|
2691
2779
|
hash of one key (a unique index on `integrations.key_hash`).
|
|
2692
2780
|
|
|
2693
|
-
**What intake
|
|
2781
|
+
**What intake checks a bundle against**, before any of it is kept. It is upgraded by
|
|
2694
2782
|
its grammar stamps and read by the bundle's schema. Each action is named
|
|
2695
2783
|
`ext.<audience>.<integration>.<name>` under the integration's own id; each of
|
|
2696
2784
|
its endpoints is a fingerprint the app serves, called on one of the app's vex
|
|
@@ -2702,7 +2790,7 @@ routed: a `..`, `.`, `%2e` or `\` that would move it is refused, and so is a
|
|
|
2702
2790
|
`{{…}}` template, which is filled in when the endpoint is called; one in the
|
|
2703
2791
|
query is taken. Its layout composes what the app's kit has; and no
|
|
2704
2792
|
chain of its steps, laid over the app's own actions, runs for ever. Then
|
|
2705
|
-
`extension` is read by the app's schema and
|
|
2793
|
+
`extension` is read by the app's schema and checked by the app's `check`. Every
|
|
2706
2794
|
reason, moss's and the app's, is reported together, and any one refuses the
|
|
2707
2795
|
bundle whole: the last good import keeps serving.
|
|
2708
2796
|
|
|
@@ -2715,7 +2803,7 @@ bundle whole: the last good import keeps serving.
|
|
|
2715
2803
|
its actions in place of the ones it shipped before, and the hash of its key
|
|
2716
2804
|
on the import a key is issued with. It lands whole, or the import before it
|
|
2717
2805
|
is still there, whole. The answer carries `key` once, on the registration
|
|
2718
|
-
whose key the row
|
|
2806
|
+
whose key the row stores: the hash is written where the row has none, so of
|
|
2719
2807
|
two registrations of one new integration in the same moment one is answered
|
|
2720
2808
|
the key and the other is answered as a later import is, with none.
|
|
2721
2809
|
- *Approve* (`POST /operator/integrations/:id/approve`) reads what the
|
|
@@ -2741,12 +2829,23 @@ bundle whole: the last good import keeps serving.
|
|
|
2741
2829
|
- *The proxy* (`/integrations/:id/*`) forwards a signed-in caller's call to an
|
|
2742
2830
|
approved integration that is installed for them, with an assertion that
|
|
2743
2831
|
says who they are. It forwards the paths the integration's actions declare
|
|
2744
|
-
as endpoints, each for whoever
|
|
2832
|
+
as endpoints, each for whoever is granted an action that declares it, and
|
|
2745
2833
|
answers `404` for any other path.
|
|
2746
2834
|
- *A webhook* (`POST /integrations/:id/hook/*`) takes no session and no
|
|
2747
2835
|
assertion is minted for it: the body goes on to the integration's service
|
|
2748
|
-
byte for byte,
|
|
2749
|
-
|
|
2836
|
+
byte for byte, and the integration checks the vendor's signature itself.
|
|
2837
|
+
The vendor's headers go with it, signature headers and `content-type`
|
|
2838
|
+
among them, but not the credentials a browser or a proxy adds:
|
|
2839
|
+
`authorization`, `cookie`, `proxy-authorization` and moss's
|
|
2840
|
+
`x-operator-key` stay behind, and so does `host`. Any web page can send a
|
|
2841
|
+
signed-in visitor's browser to the hook, so what it carries of the app's
|
|
2842
|
+
session must not leave. The headers that
|
|
2843
|
+
frame one connection (`transfer-encoding`, `keep-alive`, `expect`,
|
|
2844
|
+
`upgrade`) stay behind too: the request to the service is framed anew from
|
|
2845
|
+
the body that arrived. A request that asks to upgrade its connection
|
|
2846
|
+
(`Connection: upgrade` with `Upgrade`) is a socket upgrade, which the door
|
|
2847
|
+
never sees. One that carries `Connection: upgrade` without `Upgrade` is
|
|
2848
|
+
answered `502`: Node's fetch refuses to send that header. An integration
|
|
2750
2849
|
that is unknown or not approved answers `404`. **The door has a limit, and
|
|
2751
2850
|
it is a limit per process**: 240 calls a minute for each integration,
|
|
2752
2851
|
counted in the memory of the process that takes them, in windows of a minute
|
|
@@ -2757,6 +2856,17 @@ bundle whole: the last good import keeps serving.
|
|
|
2757
2856
|
a process that restarts counts from nothing. It is not a ceiling for the
|
|
2758
2857
|
deployment, and neither number is a setting: a deployment that needs one
|
|
2759
2858
|
ceiling across its processes sets it where they meet, at its proxy.
|
|
2859
|
+
- *How an answer is served.* What the integration's service answers, through
|
|
2860
|
+
the proxy or a webhook, goes back with its status, its body and its
|
|
2861
|
+
`content-type`, plus `x-content-type-options: nosniff` and
|
|
2862
|
+
`content-security-policy: sandbox allow-scripts allow-forms allow-popups
|
|
2863
|
+
allow-popups-to-escape-sandbox allow-modals allow-downloads
|
|
2864
|
+
allow-top-navigation`. A page a browser lands on (an OAuth `form_post`
|
|
2865
|
+
callback, a SAML POST) still runs its script, submits its forms and moves
|
|
2866
|
+
the window on, but as a page with no origin, never the app's own: it cannot
|
|
2867
|
+
read the app's cookies or browser storage, a socket it opens is refused,
|
|
2868
|
+
and a form it posts into the app carries no session cookie. A `fetch` that
|
|
2869
|
+
reads the answer is not affected by either header.
|
|
2760
2870
|
|
|
2761
2871
|
**A vendor's own page inside the app** is the app's to mount. Moss frames
|
|
2762
2872
|
none: an app that wants one serves a route of its own (`routes(server)` in
|
|
@@ -2780,12 +2890,12 @@ app's own vex entry reads `integrations.extension` as it reads any column.
|
|
|
2780
2890
|
| `extension` | what its bundle said in the app's own vocabulary, as the app's `prepare` answered it |
|
|
2781
2891
|
| `last_import_at`, `last_error` | when the last good import landed, and why the last one did not |
|
|
2782
2892
|
|
|
2783
|
-
`integration_actions`
|
|
2893
|
+
`integration_actions` has one row for each action: `integration_id`,
|
|
2784
2894
|
`action_id`, `definition`, and `grammar`, the stamps the definition is written
|
|
2785
2895
|
at.
|
|
2786
2896
|
|
|
2787
2897
|
The feature reads and writes them through vex, with entries of its own that no
|
|
2788
|
-
route serves (see [Features](#features)); it
|
|
2898
|
+
route serves (see [Features](#features)); it contains no SQL. Landing a bundle is
|
|
2789
2899
|
a batch, so `runtime.db` has to have `transaction`, as it does for any batch an
|
|
2790
2900
|
app writes.
|
|
2791
2901
|
|
|
@@ -2815,7 +2925,7 @@ const approved = async (): Promise<RegisteredIntegration<Listing>[]> => (await i
|
|
|
2815
2925
|
|
|
2816
2926
|
`{ verifyKey, mint(claims, ttlMs?) }` — the ed25519 assertion the feature signs
|
|
2817
2927
|
every call to an integration with, for a check or a service in the same
|
|
2818
|
-
workspace that wants to mint or
|
|
2928
|
+
workspace that wants to mint or keep one. An integration verifies it against
|
|
2819
2929
|
`GET /api/integrations/verify-key`.
|
|
2820
2930
|
|
|
2821
2931
|
`seed` is 32 bytes as base64, and makes the same keypair wherever it is given:
|
|
@@ -2927,7 +3037,7 @@ goes around moss: see [`FunctionSession`](#functionsession).
|
|
|
2927
3037
|
- `initial` — pass what `readDocumentSnapshot()` returned. The wire starts from
|
|
2928
3038
|
it instead of from nothing, so the first render matches the page's HTML and
|
|
2929
3039
|
the first frames off the socket confirm it. It is used only when it was drawn
|
|
2930
|
-
for who this terminal is — signed in and
|
|
3040
|
+
for who this terminal is — signed in and with a token, or neither;
|
|
2931
3041
|
anything else is somebody else's screen and the wire starts empty. Its `seed`
|
|
2932
3042
|
is named on the first connect only. Its `path` is named on every connect
|
|
2933
3043
|
(`config.path` overrides it; a page that was not drawn on the server passes
|
|
@@ -2973,7 +3083,7 @@ is the same recovery a layer down. It is also the way out of `incompatible`,
|
|
|
2973
3083
|
once the server has been updated: the connection it makes is found compatible
|
|
2974
3084
|
or not on its own account, and is retried like any other when it drops.
|
|
2975
3085
|
|
|
2976
|
-
**The wire
|
|
3086
|
+
**The wire has one socket at a time.** Before it makes one it lets go of the
|
|
2977
3087
|
one it had: its handlers come off and it is closed. That one may have closed
|
|
2978
3088
|
already, may have carried another principal, or may be a connect still in
|
|
2979
3089
|
flight when `reset()` was called; whichever, nothing it says afterwards is
|
|
@@ -3028,7 +3138,7 @@ one pressed once the connection is open drops them and is sent, because it was
|
|
|
3028
3138
|
pressed on the screen the person sees now. `publish`, `back` and `popTo` name
|
|
3029
3139
|
no canvas to check against, and are dropped unless the connection is open.
|
|
3030
3140
|
|
|
3031
|
-
`back()` sends `{ type: 'back' }` and nothing else — no location is
|
|
3141
|
+
`back()` sends `{ type: 'back' }` and nothing else — no location is kept here,
|
|
3032
3142
|
so what comes back is whatever canvases moved, over the same stream every other
|
|
3033
3143
|
change arrives on. It is dropped on a closed socket rather than queued: a back
|
|
3034
3144
|
pressed during an outage is about a screen the person is no longer being served,
|
|
@@ -3101,7 +3211,7 @@ in the subpaths.
|
|
|
3101
3211
|
status.
|
|
3102
3212
|
|
|
3103
3213
|
**The connection's status reaches every target, the same way.** When a
|
|
3104
|
-
connection drops, the trees the terminal
|
|
3214
|
+
connection drops, the trees the terminal has stay on screen: a reconnect
|
|
3105
3215
|
re-sends the current ones, and blanking in between would show a working app as
|
|
3106
3216
|
an empty one. So a screen left up by a dead socket looks exactly like a live
|
|
3107
3217
|
one, and every target is told which it is: `api.status()` is `'connecting' |
|
|
@@ -3151,7 +3261,7 @@ Requires the optional `react`/`react-dom` peers.
|
|
|
3151
3261
|
SlotWrapper. Served trees carry identity only, so its props
|
|
3152
3262
|
(`TerminalSlotWrapperProps`) are `{ canvasId, instanceId, definitionId }`
|
|
3153
3263
|
and the content as `children` — `definitionId`, not `action`.
|
|
3154
|
-
- **Adoption.** A `root` that already
|
|
3264
|
+
- **Adoption.** A `root` that already contains elements, on a wire that has a
|
|
3155
3265
|
frame, was drawn on the server from the snapshot the wire started from: the
|
|
3156
3266
|
target adopts those elements (`hydrateRoot`) instead of replacing them. An
|
|
3157
3267
|
empty root, or a wire with no frame (the page was drawn for somebody else),
|
|
@@ -3168,7 +3278,7 @@ Requires the optional `react`/`react-dom` peers.
|
|
|
3168
3278
|
one. It is drawn with the status the page's terminal starts in: `'static'`
|
|
3169
3279
|
when `live` is `false` (no socket is opened for that page), `'connecting'`
|
|
3170
3280
|
otherwise. So a kit component that draws the status draws the same thing on
|
|
3171
|
-
both sides. The same
|
|
3281
|
+
both sides. The same applies to the Vue entry below.
|
|
3172
3282
|
|
|
3173
3283
|
**What a kit owes a server-drawn page.** The first pass in the browser must
|
|
3174
3284
|
draw exactly what the server drew, so nothing that differs between the two may
|
|
@@ -3182,7 +3292,7 @@ decide a component's first render:
|
|
|
3182
3292
|
- What a component puts on `<html>` from an effect is not in the page until the
|
|
3183
3293
|
script runs; give it to `renderDocument`'s `htmlAttributes`.
|
|
3184
3294
|
|
|
3185
|
-
An app
|
|
3295
|
+
An app guards this with a check: draw the page, open it in a DOM with the real
|
|
3186
3296
|
wire and target, and assert React said nothing (atrium's and lyra's `ssr-check`).
|
|
3187
3297
|
|
|
3188
3298
|
## `@niscorp/moss/terminal/vue`
|
|
@@ -3204,7 +3314,7 @@ Requires the optional `vue` peer.
|
|
|
3204
3314
|
- `TerminalSlotWrapper` — a Vue component wrapping each action instance at
|
|
3205
3315
|
the `ActionSlot` boundary, handed `{ canvasId, instanceId, definitionId }`
|
|
3206
3316
|
as props (`TerminalSlotWrapperProps`) and the content as its default slot.
|
|
3207
|
-
- **Adoption**, as the react target: a root that
|
|
3317
|
+
- **Adoption**, as the react target: a root that contains server-drawn elements,
|
|
3208
3318
|
on a wire with a frame, is mounted with `createSSRApp` and adopted.
|
|
3209
3319
|
|
|
3210
3320
|
### `@niscorp/moss/terminal/vue/server`
|