@niscorp/moss 0.9.3 → 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 +110 -0
- package/DESIGN.md +58 -55
- package/DOCS.md +259 -168
- 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-TAAKHW3U.js → chunk-3PL4AH4I.js} +4 -4
- package/dist/{chunk-TAAKHW3U.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-U43CBKKE.cjs → chunk-6ACVHHFK.cjs} +32 -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-6MZPY4X6.js → chunk-MYPK5YZR.js} +249 -199
- 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-EXMOO7ZR.cjs → chunk-UVY5ZPWW.cjs} +326 -276
- package/dist/chunk-UVY5ZPWW.cjs.map +1 -0
- package/dist/{chunk-MVG333UF.js → chunk-VYYDLGQ2.js} +27 -25
- 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-YGZS5B2U.cjs → chunk-XH6TSWG4.cjs} +7 -7
- package/dist/{chunk-YGZS5B2U.cjs.map → chunk-XH6TSWG4.cjs.map} +1 -1
- package/dist/client.cjs +5 -5
- package/dist/client.js +2 -2
- package/dist/{document-CuF4JqzJ.d.cts → document-DvhT_HaJ.d.cts} +1 -1
- package/dist/{document-BzXQvEc1.d.ts → document-iKaRinZE.d.ts} +1 -1
- package/dist/{index-CSEo7Tys.d.cts → index-DWj3_0Zg.d.cts} +3 -0
- package/dist/{index-CSEo7Tys.d.ts → 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-6MZPY4X6.js.map +0 -1
- package/dist/chunk-EXMOO7ZR.cjs.map +0 -1
- package/dist/chunk-IY5BOFLK.cjs.map +0 -1
- package/dist/chunk-MVG333UF.js.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-U43CBKKE.cjs.map +0 -1
- package/dist/chunk-UTFOMFCH.js.map +0 -1
- package/dist/chunk-VKQPOZDJ.cjs.map +0 -1
package/DOCS.md
CHANGED
|
@@ -88,10 +88,10 @@ reaction's `run` — and `features`. Absent `shell`, the app serves data only
|
|
|
88
88
|
an org). Moss always injects `{ userId }` (the principal; `'anonymous'` for
|
|
89
89
|
nobody signed in); this contributes the rest, merged
|
|
90
90
|
server-side and asked per request, so a value derived from the clock is
|
|
91
|
-
never
|
|
91
|
+
never kept for a session. Synchronous. `identity` is the record
|
|
92
92
|
`identity.resolve` answered: absent for nobody signed in, and in an app with
|
|
93
93
|
no `identity` seam. What `scope` answers is merged over that record's
|
|
94
|
-
`scope`, the values that are
|
|
94
|
+
`scope`, the values that are kept for the session.
|
|
95
95
|
- `identity.resolve(principal, read)` — who a principal is, resolved once per
|
|
96
96
|
session and cached by moss (bounded by `runtime.identityMax` /
|
|
97
97
|
`identityIdleMs`, re-resolved every `sessionRevalidateMs`). Returns an
|
|
@@ -113,7 +113,7 @@ reaction's `run` — and `features`. Absent `shell`, the app serves data only
|
|
|
113
113
|
twice.` A map of handlers by id still works and is deprecated.
|
|
114
114
|
**`server.checkFunctions()`** builds nobody's shell once, drops it, and reads
|
|
115
115
|
what its `functions(session)` returned, so what is wrong with the functions
|
|
116
|
-
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
|
|
117
117
|
the server, as a session hook may reach for the server, after it has
|
|
118
118
|
mounted every route of its own, and before it listens. Nobody's shell
|
|
119
119
|
makes its reads in-process, and the server takes no route once it has
|
|
@@ -125,22 +125,22 @@ reaction's `run` — and `features`. Absent `shell`, the app serves data only
|
|
|
125
125
|
returned a map of handlers, which is deprecated: return a list of { id,
|
|
126
126
|
description, execute }.`, or `[moss] functions with no description:
|
|
127
127
|
auth.leave. Give each a description.` An empty description counts as none,
|
|
128
|
-
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
|
|
129
129
|
its principal's roles grant**, in the charter's `functions` part (names or
|
|
130
130
|
globs, with `extends` and `deny`, as `actions`): a role with none may call
|
|
131
131
|
none, and an `fn:` endpoint to one it does not grant fails when it is called.
|
|
132
|
-
What a living shell
|
|
132
|
+
What a living shell has follows the roles an adopt answers, as its actions
|
|
133
133
|
do.
|
|
134
|
-
- **The boot is refused** where somebody
|
|
134
|
+
- **The boot is refused** where somebody is granted an action that calls a
|
|
135
135
|
function their roles do not grant, and **`server.checkFunctions()` refuses**
|
|
136
136
|
where an action, or a fragment the shells ship, calls a function the app
|
|
137
137
|
does not have (`"home" calls "auth.leave", which the app has no function
|
|
138
138
|
of`); an app with no `functions` has none. It reads the `fn:` endpoints of
|
|
139
|
-
the actions
|
|
139
|
+
the actions granted to each role on its own, each combination `wearable` or
|
|
140
140
|
`assignments` lists, and `public`, and of the fragments the shells ship,
|
|
141
141
|
and lists every call that is missing: `"member" hold "chrome.topbar",
|
|
142
142
|
which calls "auth.leave": their functions do not grant it`. A set handed
|
|
143
|
-
over while the app runs is
|
|
143
|
+
over while the app runs is checked the same way. A name with a template in it
|
|
144
144
|
(`fn: '{{$.saveFn}}'`) is worked out when it is called, and the shell's map
|
|
145
145
|
decides then.
|
|
146
146
|
- **`functions: ['*']`** grants every function, as an app had before this
|
|
@@ -182,7 +182,7 @@ reaction's `run` — and `features`. Absent `shell`, the app serves data only
|
|
|
182
182
|
`reconcile` step aims at it (nova's SHELL_DOCS.md, "A canvas that names its
|
|
183
183
|
own reconciler"): handed each row as written, it decides what is kept,
|
|
184
184
|
matched, moved and removed — several cards of one action on one list canvas,
|
|
185
|
-
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
|
|
186
186
|
them, the app's and each page's, the one a document is drawn from and the
|
|
187
187
|
socket's: from one seed, a reconciler that answers the same rows the same
|
|
188
188
|
way places the same instances in both. A reconciler
|
|
@@ -217,7 +217,7 @@ charter's `layouts` section selects who is granted which variant id, and moss
|
|
|
217
217
|
puts the granted variant's layout where that action's layout is kept in the
|
|
218
218
|
shell ("Where an action's layout is kept", under `createServer`). The base is
|
|
219
219
|
the floor; variants enrich upward as grants. A role, or a combination
|
|
220
|
-
of roles somebody may wear, that
|
|
220
|
+
of roles somebody may wear, that is granted two variants of one action refuses the
|
|
221
221
|
boot, and so does a variant of an action the app does not have.
|
|
222
222
|
|
|
223
223
|
#### `ShellManifest`
|
|
@@ -246,15 +246,15 @@ they generated.
|
|
|
246
246
|
A `CanvasSeed` is an action id or `{ action, input?, with? }`, and a
|
|
247
247
|
`ShellCanvas` is nova's canvas config with `initial` widened to one seed or a
|
|
248
248
|
list of candidates. Neither type is exported by name: `ShellManifest['canvases']`
|
|
249
|
-
carries both. Of a list of candidates, the first action the principal
|
|
250
|
-
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
|
|
251
251
|
`reconcile` names one of the app's `reconcilers`.
|
|
252
252
|
|
|
253
253
|
`components` is the kit as the server knows it: each component's name, with
|
|
254
254
|
its `meta` (a `description`, and `propsSchema`, the zod schema of its props).
|
|
255
255
|
A name listed there is registered in the shell whether or not a layout of the
|
|
256
256
|
app uses it. The `components` of the app's own `shell` are also the kit a
|
|
257
|
-
bundle's layouts are
|
|
257
|
+
bundle's layouts are checked against at intake, and the one the integrations'
|
|
258
258
|
contract lists ([`@niscorp/moss/integrations`](#niscorpmossintegrations)): a
|
|
259
259
|
bundle's layout that uses a component not listed there is refused, and where
|
|
260
260
|
a component's `propsSchema` is a zod object, so is a prop it has no place for.
|
|
@@ -363,7 +363,7 @@ throw, and so do `set` and `delete` on its `layoutStore`, which is to read. A
|
|
|
363
363
|
definition read off it (`shell.getRuntime(id).definition`) is the action as it
|
|
364
364
|
was written, with the layout it is drawn with now in place: where moss keeps a
|
|
365
365
|
layout does not show. An action, a fragment, a canvas, a layout and the phrases reach a shell
|
|
366
|
-
through moss, which verifies them and decides who
|
|
366
|
+
through moss, which verifies them and decides who is granted them; added on the
|
|
367
367
|
shell directly they are not verified, are in nobody's catalog and are gone
|
|
368
368
|
when the shell is rebuilt. Everything else (reads, navigation, `dispatch`,
|
|
369
369
|
`publish`, the observers) works as on nova's `Shell`, which is still the
|
|
@@ -379,9 +379,9 @@ import type { ActionDefinition } from '@niscorp/nova';
|
|
|
379
379
|
const register = (session: FunctionSession, definition: ActionDefinition): void => unverifiedShell(session).registerAction(definition);
|
|
380
380
|
```
|
|
381
381
|
|
|
382
|
-
**A session says who is calling and
|
|
382
|
+
**A session says who is calling and has no key.** It carries no `runtime`
|
|
383
383
|
(the database pool, the operator key) and no `policy` (the
|
|
384
|
-
object the routes enforce for everybody
|
|
384
|
+
object the routes enforce for everybody wearing those roles). What app code
|
|
385
385
|
needs of either has a call:
|
|
386
386
|
|
|
387
387
|
- **A read or a write as the caller**: `session.wire`, the routes, enforced.
|
|
@@ -391,7 +391,8 @@ needs of either has a call:
|
|
|
391
391
|
intent and the shape. The query is written, compiled and run under the
|
|
392
392
|
policy and the scope values the routes serve this principal under, resolved
|
|
393
393
|
when it is asked: the writer is shown only the tables they may read, and a
|
|
394
|
-
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
|
|
395
396
|
routes replay from, so `answer.meta.cache.fingerprint` replays over
|
|
396
397
|
`session.wire` afterwards, for whoever the policy lets. Moss keeps one
|
|
397
398
|
engine for each `writers` object: hand over the same object each time. It
|
|
@@ -493,8 +494,18 @@ functions: (session) => [
|
|
|
493
494
|
theirs whose newest version was neither saved nor used within that time is
|
|
494
495
|
deleted, every version of it, by a sweep that runs as the server comes up and
|
|
495
496
|
then every hour. What is published for everybody never ages, and what the
|
|
496
|
-
build ships is not a row. Without the setting nothing is deleted. A limit
|
|
497
|
-
|
|
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.
|
|
498
509
|
- **It reaches its owner's open shells a moment after the save answers**, as a
|
|
499
510
|
saved layout does, and not before: a function that saves an action and
|
|
500
511
|
opens it in the same call finds it not there yet. One that is to be seen at
|
|
@@ -519,20 +530,20 @@ functions: (session) => [
|
|
|
519
530
|
endpoints, and where both define an endpoint of one name the action's is
|
|
520
531
|
the one called. What an assistant is told it may generate is the app's to
|
|
521
532
|
decide: it writes the prompt, and its own function calls `save`.
|
|
522
|
-
- **A generated action opens the actions its owner
|
|
533
|
+
- **A generated action opens the actions its owner is granted**, their own
|
|
523
534
|
generated ones among them, and no other: nova's audit is run on it with
|
|
524
535
|
those as its catalog, and what it finds refuses the save, as it does for a
|
|
525
536
|
saved layout. So do a component no shell of the app has, and a layout that
|
|
526
|
-
names a ref moss keeps a layout under (`action/…`, `canvas/…`, `frame`). A fragment is
|
|
527
|
-
layout and its endpoints, and not
|
|
528
|
-
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
|
|
529
540
|
by nova when it runs, because that action is not in their shell.
|
|
530
541
|
- **It is checked when it is saved and again when a shell is built.** One
|
|
531
542
|
that no longer passes (its owner lost the grant its read needs, say) is left
|
|
532
543
|
out of every shell built from then on, with a line (`[moss] the action "…"
|
|
533
544
|
of … is left out: …`).
|
|
534
545
|
- **A reset takes it out of its owner's shells**, and the layouts they saved
|
|
535
|
-
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
|
|
536
547
|
no longer is not loaded. `list('layout')` still lists them. Going back to a
|
|
537
548
|
version of the action brings both back.
|
|
538
549
|
- **No action an app ships or hands over, and no fragment of a shell, has an
|
|
@@ -552,7 +563,7 @@ whose `principal` is their `userId`, and a row they insert or update carries
|
|
|
552
563
|
it, whatever the statement says. Vex keeps that rule on every read and every
|
|
553
564
|
write; moss's code passes no principal. **Who may save at all is the charter's**: a function that calls
|
|
554
565
|
`session.artifacts.save` is the app's, an action calls it, and the charter
|
|
555
|
-
says who
|
|
566
|
+
says who is granted that action. A session nobody is signed in to saves nothing
|
|
556
567
|
and lists nothing: everybody who is not signed in shares one `userId`.
|
|
557
568
|
|
|
558
569
|
- The layout is the principal's and nobody else's. Moss gives it its id, a
|
|
@@ -574,16 +585,17 @@ or write a row of another account.
|
|
|
574
585
|
|
|
575
586
|
**A read vex wrote** for a request (`session.answerIntent`) is saved under
|
|
576
587
|
the fingerprint vex gave it, with no body:
|
|
577
|
-
`session.artifacts.save([{ kind: 'read', id: 'fp_…' }])`.
|
|
578
|
-
from vex's own table and keeps it as written: the query,
|
|
579
|
-
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.
|
|
580
592
|
|
|
581
593
|
- **It is answered to the person who saved it and to nobody else.** When one
|
|
582
594
|
of their requests replays that fingerprint, moss answers it, compiled, from
|
|
583
595
|
their rows. Anybody else who sends the fingerprint gets what vex's own table
|
|
584
|
-
still
|
|
596
|
+
still has under it, as for any query vex wrote and nobody saved, and a
|
|
585
597
|
caller nobody is signed in for is never answered a saved read.
|
|
586
|
-
- **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
|
|
587
599
|
(`maxLimit`), as they do not to an entry the app ships. A request that names
|
|
588
600
|
its fingerprint with an intent and a shape is written anew by vex into its
|
|
589
601
|
own table; the saved read is what its owner is answered until they save the
|
|
@@ -608,12 +620,12 @@ its mapping, its shape and its intent.
|
|
|
608
620
|
|
|
609
621
|
**What a shell draws under an action's ref**, the first of these that there
|
|
610
622
|
is: the principal's own layout marked in use; the layout variant their roles
|
|
611
|
-
|
|
623
|
+
are granted (`app.layouts`); the layout published for everybody that is marked in use
|
|
612
624
|
(`server.defaults`); the layout the build ships.
|
|
613
625
|
|
|
614
626
|
**What is refused**, at a save and at a restore, in a sentence, with nothing
|
|
615
627
|
written: a body that is not `{ ref, layout, use? }`; a `ref` nothing is kept
|
|
616
|
-
under for the principal (an action they
|
|
628
|
+
under for the principal (an action they are not granted, or one that is not in
|
|
617
629
|
force; an action with no layout of its own, or one that names a layout of the
|
|
618
630
|
store by its id; any name that is none of `action/<id>`, `frame` and
|
|
619
631
|
`canvas/<id>`); a component no shell of
|
|
@@ -626,8 +638,8 @@ a control the action listens on that the layout leaves out, a control no
|
|
|
626
638
|
trigger handles). The same is asked of every saved layout when a shell is
|
|
627
639
|
built, there against the components of that shell alone: one that does not
|
|
628
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
|
|
629
|
-
its
|
|
630
|
-
|
|
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.
|
|
631
643
|
|
|
632
644
|
**The layouts of the app's own shell** are saved with the same calls: its own
|
|
633
645
|
under `ref: 'frame'`, and a canvas's under `ref: 'canvas/<the canvas's id>'`.
|
|
@@ -659,20 +671,22 @@ true } }])`.
|
|
|
659
671
|
gives a shell a canvas when something is first pushed onto it, whether or not
|
|
660
672
|
its manifest declares it, and it is drawn where a layout has a canvas slot for
|
|
661
673
|
it (`{ component: 'CanvasSlot', props: { canvasId: 'notes' } }`). Moss reads
|
|
662
|
-
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
|
|
663
675
|
manifest does not declare. Every layout counts (the frame, a canvas's, an
|
|
664
|
-
action's that the principal
|
|
676
|
+
action's that the principal is granted, a fragment's, one the app keeps in its
|
|
665
677
|
layout store), the build's and a saved or generated one alike. Once a layout
|
|
666
|
-
leaves force and no other
|
|
678
|
+
leaves force and no other has a slot for such a canvas, an open shell loses
|
|
667
679
|
the canvas, with what is mounted on it. A slot whose `canvasId` is worked out
|
|
668
680
|
when it is drawn (`'$.c.id'`, a template) counts for none. Moss gives a shell
|
|
669
681
|
no canvas, and the canvases a manifest declares are never taken out. What is
|
|
670
682
|
pushed onto a canvas after its slot went is mounted and drawn nowhere, as on
|
|
671
683
|
any canvas no layout has a slot for.
|
|
672
684
|
|
|
673
|
-
**
|
|
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
|
|
674
688
|
of the principal's artifacts that has a body. `history` answers the versions
|
|
675
|
-
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
|
|
676
690
|
a copy of a version and says which (`copiedFrom`); it is checked as a save
|
|
677
691
|
is. `reset` is a new save whose version has no body: none of the principal's
|
|
678
692
|
is in force under that id, and what is under it is drawn again. A reset is a
|
|
@@ -682,7 +696,7 @@ drawn. The next save that marks one for that ref, or takes the one in use out
|
|
|
682
696
|
(a reset, or a save of it without the mark), takes the mark off the rest.
|
|
683
697
|
|
|
684
698
|
The rows are in `artifact_saves` (one for each save) and `artifacts` (one for
|
|
685
|
-
each version a save
|
|
699
|
+
each version a save contains), which migration `nisc.moss/5` makes. They are
|
|
686
700
|
read and written through three vex entries of moss's own that no route serves
|
|
687
701
|
(`src/artifactory/saves.ts`). What is in force for an artifact is its latest
|
|
688
702
|
version by `created_at`; every id moss gives is a uuid. A body is kept with
|
|
@@ -763,9 +777,9 @@ functions: (session) => [
|
|
|
763
777
|
refuses**, with the same sentences. Each artifact is checked beside what is
|
|
764
778
|
in force for the principal with the draft laid over, so a layout may be for
|
|
765
779
|
an action that is itself in the draft. A draft is one shell's, so what is
|
|
766
|
-
added to it is
|
|
767
|
-
those of any shell of the app. A new action or fragment
|
|
768
|
-
`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
|
|
769
783
|
one in the draft, or one the principal saved: a new take of it, which stands
|
|
770
784
|
in for the saved one in this shell until the draft is saved or the take is
|
|
771
785
|
taken out. An add that marks a layout `use: true` takes the mark off the
|
|
@@ -777,13 +791,13 @@ functions: (session) => [
|
|
|
777
791
|
- **What the shell draws**: what is in the draft, then what `session.artifacts`
|
|
778
792
|
would draw. A drafted layout marked `use: true` is drawn in place of a saved
|
|
779
793
|
one that is marked for the same ref.
|
|
780
|
-
- **`list`** answers what the draft
|
|
794
|
+
- **`list`** answers what the draft contains, and **`remove`** takes one out of
|
|
781
795
|
it; what is under it is drawn again. **`discard`** empties it.
|
|
782
796
|
- **Each add or removal is a numbered step**, from 1. **`show(step)`** has the
|
|
783
797
|
shell show the draft as it was after that step, and `show(0)` none of it. A
|
|
784
798
|
add or a removal while an earlier step is shown goes on from that step: the
|
|
785
799
|
steps after it are dropped. The steps are the draft's and are saved nowhere.
|
|
786
|
-
- **`save`** is one save of what the draft
|
|
800
|
+
- **`save`** is one save of what the draft contains, as the principal's own and
|
|
787
801
|
under the ids it had, checked once more. The draft is then empty and the
|
|
788
802
|
shell keeps what it shows. An empty draft is refused.
|
|
789
803
|
- **Calls on one draft are taken in turn**: each starts from the draft as the
|
|
@@ -803,12 +817,15 @@ type NiscRuntime = {
|
|
|
803
817
|
db: MutationClient; // writes
|
|
804
818
|
cache?: CacheBackend; // defaults to vex's postgres cache on `pool`
|
|
805
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
|
|
806
822
|
session: SessionVerifier | 'sessions' | 'dev-open'; // REQUIRED — no default
|
|
807
823
|
origins?: readonly string[]; // origins that are the app's own page, beside the host a request names (a proxy that rewrites `Host`)
|
|
808
824
|
migrations?: 'apply' | 'verify'; // the boot's ledgered run; default 'verify'
|
|
809
825
|
tables?: readonly Sequence[]; // the app's own table sequences, in that same run
|
|
810
826
|
shellIdleMs?: number; // idle shell eviction; default 30 min, `0` disables
|
|
811
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
|
|
812
829
|
anonymousShellMax?: number; // shells for nobody signed in alive at once; default 1,000, `Infinity` is no limit
|
|
813
830
|
endpointTimeoutMs?: number; // a server shell's endpoint call, and the build of a shell; default nova's, 30s
|
|
814
831
|
sessionRevalidateMs?: number; // live-socket re-verify; default 60s, `0` disables
|
|
@@ -830,7 +847,7 @@ the function form of `session`. The type is not exported by name.
|
|
|
830
847
|
`socketCompression` and `socketMaxMessageBytes` are settings of the Node
|
|
831
848
|
transport. The server reads them, once, and the socket it hands out
|
|
832
849
|
(`server.socket`) carries them to whichever transport is handed it. So they
|
|
833
|
-
|
|
850
|
+
apply wherever that socket is attached: under `serve`, `nisc start`, the dev
|
|
834
851
|
plugin (`nisc dev`), and a host of the app's own that calls
|
|
835
852
|
`attachSocket(httpServer, server.socket)`. No host says them again.
|
|
836
853
|
|
|
@@ -841,6 +858,19 @@ own reads and writes. The generation counter and a feature's own entries (the
|
|
|
841
858
|
integrations' registry) read the tables that are theirs off the database
|
|
842
859
|
whatever the list names, and know no other table.
|
|
843
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
|
+
|
|
844
874
|
`session` is required, deliberately — authentication is the one door that must
|
|
845
875
|
not default open, and it used to. Three answers: `'sessions'` uses moss's own
|
|
846
876
|
stored credential (below); `'dev-open'` trusts every well-formed token and says
|
|
@@ -861,7 +891,7 @@ asked about again, an identity record older than it is resolved again when it
|
|
|
861
891
|
is next read, and the generation pointer is polled
|
|
862
892
|
([Many processes](#many-processes)). `0` turns off all three, and so does
|
|
863
893
|
`Infinity` or any interval above 2^31 − 1 ms (24.8 days), the longest a timer
|
|
864
|
-
of Node's
|
|
894
|
+
of Node's can wait: a process then follows no `refresh`, `replaceActions` or
|
|
865
895
|
approval of an integration that another process made.
|
|
866
896
|
|
|
867
897
|
`operatorKey` is what a request under `/operator` presents as
|
|
@@ -885,10 +915,10 @@ Somebody signed in is served whatever the count is, and a shell one of the
|
|
|
885
915
|
manifest's pages builds for somebody signed in takes no place.
|
|
886
916
|
|
|
887
917
|
**What the limit is, exactly.** One count, for everybody with nobody signed
|
|
888
|
-
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
|
|
889
919
|
it does nothing else:
|
|
890
920
|
|
|
891
|
-
- It is not a limit for each visitor. Whoever
|
|
921
|
+
- It is not a limit for each visitor. Whoever takes the places keeps them:
|
|
892
922
|
one client that opens `anonymousShellMax` connections and keeps them open
|
|
893
923
|
has every place, and every other visitor with nobody signed in is sent
|
|
894
924
|
`at_capacity` until one of those closes. People who are signed in go on
|
|
@@ -902,20 +932,20 @@ it does nothing else:
|
|
|
902
932
|
close is like any other: the place is given back, a shell for nobody is
|
|
903
933
|
disposed, and a signed-in person's shell starts its idle time.
|
|
904
934
|
- It is counted by the process that takes the connection. A deployment of N
|
|
905
|
-
processes
|
|
935
|
+
processes allows up to N times the limit.
|
|
906
936
|
- Moss builds no limit for each address, because the address is not moss's
|
|
907
937
|
to know: behind a proxy every connection comes from the proxy, and which
|
|
908
938
|
header says where the visitor is, is the proxy's to say.
|
|
909
939
|
|
|
910
940
|
**A deployment that faces the internet** limits how many connections one
|
|
911
|
-
address may
|
|
941
|
+
address may keep open where the address is known: at its proxy or load balancer,
|
|
912
942
|
on the socket's path (`/socket`). With that in place, `anonymousShellMax` is
|
|
913
943
|
what it is sized for here, memory. What an app can do on its own: a first
|
|
914
944
|
screen for nobody that is a page which is not live opens no socket and takes
|
|
915
945
|
no place (`nisc build` says which pages are live, and why).
|
|
916
946
|
|
|
917
947
|
The default is from a measurement (2026-10-10, Node 24): lyceum's real boot,
|
|
918
|
-
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
|
|
919
949
|
read after a forced collection before and after, with a transport that drops
|
|
920
950
|
what it is sent.
|
|
921
951
|
|
|
@@ -943,7 +973,7 @@ the row.
|
|
|
943
973
|
its own identity check and hands the token to the terminal (or sets it as
|
|
944
974
|
the browser's cookie, [`sessionCookies`](#sessioncookiespage-token-options)).
|
|
945
975
|
Expired rows are swept on every mint — no timer to run.
|
|
946
|
-
- `revokeAllFor` deletes every token a principal
|
|
976
|
+
- `revokeAllFor` deletes every token a principal has: signed out everywhere.
|
|
947
977
|
`session.revoke()` in a function calls it for the session's own principal;
|
|
948
978
|
this is for signing out somebody else (an owner removes a member).
|
|
949
979
|
No exported call deletes one token and leaves the principal's others.
|
|
@@ -963,10 +993,10 @@ the row.
|
|
|
963
993
|
in a function closes that principal's terminals and disposes their shell,
|
|
964
994
|
and forgets nothing: the app deletes its own credential where it signs
|
|
965
995
|
somebody out. An app that wants moss's stored sessions and a rule of its
|
|
966
|
-
own on top (a member who was removed,
|
|
996
|
+
own on top (a member who was removed, a suspended account) sets
|
|
967
997
|
`session: 'sessions'` and puts the rule where it belongs: `revokeAllFor`
|
|
968
998
|
when the member is removed, or `identity.resolve` answering
|
|
969
|
-
`{ roles: ['public'], scope: {} }` for somebody who may
|
|
999
|
+
`{ roles: ['public'], scope: {} }` for somebody who may be granted nothing.
|
|
970
1000
|
|
|
971
1001
|
```typescript
|
|
972
1002
|
// the app's own door: who they are is the app's to establish, then a session
|
|
@@ -1022,7 +1052,7 @@ reason as `fingerprint: why` — and nothing was applied. It asks on every run,
|
|
|
1022
1052
|
so a release that changes an entry and no table is checked too.
|
|
1023
1053
|
|
|
1024
1054
|
One kind of entry is said and not refused: one that already did not fit before
|
|
1025
|
-
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
|
|
1026
1056
|
is an old fault, not this run's. A new or changed entry gets no such pass. A
|
|
1027
1057
|
copy is there where a release before 0.6.0 wrote it, or where the app writes
|
|
1028
1058
|
one itself for an engine of its own (`seedCache`). Moss writes none since
|
|
@@ -1107,7 +1137,7 @@ order: the manifest is read and frozen; who a token is is resolved
|
|
|
1107
1137
|
the tables are checked (migrated under `migrations: 'apply'`) and the data
|
|
1108
1138
|
module stands; the running manifest is
|
|
1109
1139
|
created, which is the boot check, and the data module is told to ask it for an
|
|
1110
|
-
entry (it compiles the ones it
|
|
1140
|
+
entry (it compiles the ones it keeps, and one vex cannot run refuses the boot);
|
|
1111
1141
|
identity; the server's own routes (the
|
|
1112
1142
|
authentication, `/catalog`, vex); the shell hosts, the app's and each page's;
|
|
1113
1143
|
what crosses processes; the features, each started with seams made for it; the
|
|
@@ -1115,22 +1145,22 @@ operator prefix; the app's reactions hear a write; the generation pointer is
|
|
|
1115
1145
|
watched; the socket.
|
|
1116
1146
|
A step that refuses is the boot's refusal.
|
|
1117
1147
|
|
|
1118
|
-
**Where the app's entries are
|
|
1119
|
-
(`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
|
|
1120
1150
|
app shipped and each set handed over with `server.replaceEntries`, compiled as
|
|
1121
1151
|
vex replays them, and it is what the engine asks first: a request's
|
|
1122
1152
|
fingerprint, and the list of fingerprints a feature or the operator is told
|
|
1123
1153
|
of, resolve there. So what a fingerprint resolves to is what this process's
|
|
1124
1154
|
app ships, read from the build at every boot.
|
|
1125
1155
|
|
|
1126
|
-
What the running manifest does not
|
|
1156
|
+
What the running manifest does not have is asked of the cache table
|
|
1127
1157
|
(`vex_cache`, or the cache `runtime.cache` hands over). That table keeps what
|
|
1128
1158
|
vex wrote itself while the app runs: a query `session.answerIntent` wrote.
|
|
1129
1159
|
**Nothing is copied into it at boot, and a row in it that no request wrote is
|
|
1130
1160
|
not replayed.** Vex gives a query it writes the hash of the request it was
|
|
1131
1161
|
written for, and that is what moss asks of a row before it answers from it. A
|
|
1132
1162
|
release before 0.6.0 copied every entry of the app there at each boot, and a
|
|
1133
|
-
database that ran one still
|
|
1163
|
+
database that ran one still has those rows, which carry no such hash. Moss
|
|
1134
1164
|
answers from none of them and deletes none: an entry the app no longer ships
|
|
1135
1165
|
is refused (`cache_miss`). Two things an app may have leaned on are gone with
|
|
1136
1166
|
the copy:
|
|
@@ -1146,7 +1176,7 @@ the copy:
|
|
|
1146
1176
|
`action/<id>`. An app goes on writing an action's layout in its definition;
|
|
1147
1177
|
where a shell is built, moss moves it into the store, and the definition the
|
|
1148
1178
|
shell is handed names it by `{ ref: 'action/<id>' }`. A layout variant the
|
|
1149
|
-
person's roles
|
|
1179
|
+
person's roles are granted is what the store keeps under that name instead. An action
|
|
1150
1180
|
with no layout, or one whose `layout` is already the name of a stored layout,
|
|
1151
1181
|
is handed over as it is. Three things follow:
|
|
1152
1182
|
|
|
@@ -1157,7 +1187,7 @@ is handed over as it is. Three things follow:
|
|
|
1157
1187
|
endpoints and its triggers.
|
|
1158
1188
|
- **Code that reads an action's definition off its session's shell**
|
|
1159
1189
|
(`session.shell.getRuntime(id).definition`) finds it as it was written, with
|
|
1160
|
-
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
|
|
1161
1191
|
shows. `server.actions()` answers the definitions as they were written too.
|
|
1162
1192
|
Only the whole shell (`unverifiedShell(session)`), which is nova's own,
|
|
1163
1193
|
shows `{ ref }`; there the layout is `shell.layoutStore.get('action/<id>')`.
|
|
@@ -1203,11 +1233,11 @@ The manifest does not parse — refusing to serve:
|
|
|
1203
1233
|
Each line is a place and what was expected there. An action, a fragment and a
|
|
1204
1234
|
layout (a layout variant's, a canvas's, the frame's, the layout store's) are
|
|
1205
1235
|
read by nova's schemas; an entry's `dsl` and `mutation` by vex's and its
|
|
1206
|
-
`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
|
|
1207
1237
|
the shape `NiscApp` gives it, and a field `NiscApp` does not have is refused.
|
|
1208
|
-
A code seam is
|
|
1238
|
+
A code seam is checked to be a function. A component's contract
|
|
1209
1239
|
(`shell.components`) is the kit's own record and may carry more than moss
|
|
1210
|
-
names. The charter and `behaviors` are
|
|
1240
|
+
names. The charter and `behaviors` are checked to be objects; the charter is
|
|
1211
1241
|
verified by the check below and `behaviors` by vex when a policy is compiled.
|
|
1212
1242
|
|
|
1213
1243
|
**Then it is frozen**, every level of it, in place. Once `createServer` has
|
|
@@ -1241,7 +1271,8 @@ feature serves).
|
|
|
1241
1271
|
|
|
1242
1272
|
The socket is not a Hono route: `server.socket` is fed by the runtime's
|
|
1243
1273
|
transport (`/socket` under `serve` and `attachSocket`). Every request is
|
|
1244
|
-
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
|
|
1245
1276
|
through the `session` verifier (`401` when it does not resolve); a token
|
|
1246
1277
|
whose prefix a feature registered is that feature's to read (the integrations
|
|
1247
1278
|
read `ik_`, an integration key); no header is the anonymous principal. There
|
|
@@ -1281,7 +1312,7 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
|
|
|
1281
1312
|
where it cannot see (a role, an install): run the check boot runs over what
|
|
1282
1313
|
is in force (the charter, every entry's reach, the layout variants), drop
|
|
1283
1314
|
every per-principal memo and identity record, and have every living shell
|
|
1284
|
-
adopt: it is brought level with what its principal
|
|
1315
|
+
adopt: it is brought level with what its principal is granted now, in place
|
|
1285
1316
|
("A change is the server's", under `shells` below). Every living shell is
|
|
1286
1317
|
the one kept for each signed-in person, the one built for each connection
|
|
1287
1318
|
of nobody signed in, and the one a page built for each connection. It also
|
|
@@ -1322,7 +1353,7 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
|
|
|
1322
1353
|
is refused from then on, and a name a feature keeps is not the app's. The
|
|
1323
1354
|
entries in force are what the app shipped, then each set: an entry of a set
|
|
1324
1355
|
is replayed in place of one the app shipped under the same fingerprint, for
|
|
1325
|
-
as long as the set
|
|
1356
|
+
as long as the set contains it. Every entry is read by the schema the
|
|
1326
1357
|
manifest's entries are read by, compiled, and checked before the set is
|
|
1327
1358
|
taken: a write by vex's authoring lint, and the reach an entry declares by
|
|
1328
1359
|
the check boot runs. Refused, the promise rejects with what was found
|
|
@@ -1344,14 +1375,14 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
|
|
|
1344
1375
|
shows the build's again. **A layout:** `server.defaults(who).save([{ kind:
|
|
1345
1376
|
'layout', body: { ref: 'action/<id>', layout, use: true } }])` is drawn under
|
|
1346
1377
|
that action's ref unless its principal has a layout of their own in use or
|
|
1347
|
-
their roles
|
|
1378
|
+
their roles are granted a layout variant; `ref: 'frame'` and `ref: 'canvas/<id>'`
|
|
1348
1379
|
publish the layouts of the app's own shell. **An action or a fragment** is
|
|
1349
1380
|
given its id by whoever publishes it, as a shipped one has one: `save([{
|
|
1350
1381
|
kind: 'action', id: 'promo', body }])`; one without an id is refused, and so
|
|
1351
1382
|
is one under `generated.`. The charter grants it by that id, so a new id
|
|
1352
1383
|
needs a grant and one that is a shipped action's or fragment's replaces the
|
|
1353
1384
|
build's for everybody until it is reset. **A read** vex wrote is published
|
|
1354
|
-
under its fingerprint, `save([{ kind: 'read', id: '<fingerprint>' }])`, and is
|
|
1385
|
+
under its fingerprint, `save([{ kind: 'read', id: '<fingerprint>', body: undefined }])`, and is
|
|
1355
1386
|
answered to everybody after what the caller saved themselves; one under the
|
|
1356
1387
|
fingerprint of a shipped entry is refused. `publisher` is who the publish is
|
|
1357
1388
|
made by, kept with the save (`artifact_saves.created_by`); an empty one is
|
|
@@ -1370,9 +1401,9 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
|
|
|
1370
1401
|
calls are ones the publisher's roles grant, its reads ones they may replay,
|
|
1371
1402
|
no write), and then the whole as a manifest, as a set handed over is:
|
|
1372
1403
|
`Publish refused — actions call functions the app does not have, or that
|
|
1373
|
-
their holders’ charter does not grant:` lists
|
|
1374
|
-
|
|
1375
|
-
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
|
|
1376
1407
|
layout, an action or a fragment on its own where its own check refuses it
|
|
1377
1408
|
(`[moss] the action "…" published for everybody is left out: …`), and the
|
|
1378
1409
|
actions and fragments all together where the manifest refuses them (`[moss]
|
|
@@ -1380,7 +1411,7 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
|
|
|
1380
1411
|
…`). Once `checkFunctions` has read the app's functions, the rows are read
|
|
1381
1412
|
again against them: a published action calling a function a new build
|
|
1382
1413
|
dropped is left out, and the boot is not refused. When a shell is built, for
|
|
1383
|
-
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
|
|
1384
1415
|
not loaded, and a published fragment a shell cannot draw is left out of that
|
|
1385
1416
|
shell (`[moss] the fragment "…" published for everybody is left out of a
|
|
1386
1417
|
shell that cannot draw it: …`).
|
|
@@ -1391,16 +1422,16 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
|
|
|
1391
1422
|
A publish has every living shell adopt, as `refresh` does, and moves the
|
|
1392
1423
|
pointer, whether or not the rows can be read back: every other process on
|
|
1393
1424
|
the same database follows the pointer and reads them.
|
|
1394
|
-
- `catalogOf(principal): Promise<{ ids, hash }>` — what a principal
|
|
1425
|
+
- `catalogOf(principal): Promise<{ ids, hash }>` — what a principal is granted of the
|
|
1395
1426
|
actions in force: `{ ids, hash }`, the granted action ids sorted, with a
|
|
1396
1427
|
content-hash version token (equal hash, equal application). The principal is
|
|
1397
1428
|
resolved the way a request resolves it (the `identity` seam, or
|
|
1398
1429
|
`assignments`), so an integration's actions are there only where it is
|
|
1399
1430
|
installed. `null` is nobody signed in.
|
|
1400
|
-
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
|
|
1401
1432
|
they are resolved to be, installs included, and the server resolves it.
|
|
1402
1433
|
- `policyForRoles(roles): ScopePolicy` — what a set of roles may read and
|
|
1403
|
-
write: the vex policy a request by somebody
|
|
1434
|
+
write: the vex policy a request by somebody wearing exactly these roles is
|
|
1404
1435
|
served under, compiled from the charter and `behaviors` over every table the
|
|
1405
1436
|
database has. **One policy per role, merged** — a person may wear several (an
|
|
1406
1437
|
instructor who also trains here), and reach belongs to the role rather than
|
|
@@ -1410,8 +1441,9 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
|
|
|
1410
1441
|
- `charterReport(): VerifyReport` — the report `verifyCharter` gave this server:
|
|
1411
1442
|
boot's, then that of each change that passed. `{ errors, warnings,
|
|
1412
1443
|
perRole }`, over the universes boot resolved against. Boot and `refresh` read
|
|
1413
|
-
`errors
|
|
1414
|
-
|
|
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
|
|
1415
1447
|
`allow` that matches nothing) and each role's closure `issues`. `errors` is
|
|
1416
1448
|
always empty here. A push whose target is a binding (`@event.payload`,
|
|
1417
1449
|
`$.target`) is listed among the `issues` as "not in the catalog", though it is
|
|
@@ -1419,23 +1451,24 @@ It's a Hono app — mount it, extend it, or hand it to a listener.
|
|
|
1419
1451
|
- `invalidateIdentity(principal): boolean` — forget one principal's identity
|
|
1420
1452
|
record and reset every living shell of theirs (a role change): the one the
|
|
1421
1453
|
app keeps for them, and the one a page built for each connection of theirs.
|
|
1422
|
-
`false` = no record was
|
|
1454
|
+
`false` = no record was kept.
|
|
1423
1455
|
- `invalidateTag(tag): number` — forget every identity record wearing the
|
|
1424
1456
|
tag the app put on it (`IdentityRecord.tag`); answers how many. Then every
|
|
1425
1457
|
living shell adopts, as after `refresh` ("A change is the server's", under
|
|
1426
|
-
`shells` below): it is brought level with what its principal
|
|
1427
|
-
place, so a function or an action their new roles do not grant is no
|
|
1428
|
-
|
|
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
|
|
1429
1461
|
living shell, not only those of the records forgotten: a record can be
|
|
1430
1462
|
dropped while its shell lives (past `runtime.identityMax`, or unread for
|
|
1431
1463
|
`runtime.identityIdleMs`), and no tag finds it then. So each call asks the app's
|
|
1432
1464
|
`identity` again for every signed-in person with a living shell whose
|
|
1433
|
-
record is not
|
|
1465
|
+
record is not kept.
|
|
1434
1466
|
- `identity(principal): Promise<IdentityRecord>` — who one principal is,
|
|
1435
1467
|
resolved the way a request resolves it: `{ roles, scope, installed? }`,
|
|
1436
1468
|
through the same cache the request path uses. `null` is nobody signed in.
|
|
1437
1469
|
With no `identity` seam the roles are the ones `assignments` names, and
|
|
1438
|
-
`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.
|
|
1439
1472
|
- `identities?: { list(); meter() }` — the resident identity
|
|
1440
1473
|
roster (`{ principal, since, lastSeen }`) and what the cache costs
|
|
1441
1474
|
(`{ size, max, resolved, evicted, expired }`). Present only when the app
|
|
@@ -1532,17 +1565,17 @@ is live when something on it can still happen:
|
|
|
1532
1565
|
|
|
1533
1566
|
What can be pressed is read off the layout a screen is drawn with: a `{ ref }`
|
|
1534
1567
|
in it, the one an action's own layout is named by included, is read through
|
|
1535
|
-
to the layout the shell's store
|
|
1568
|
+
to the layout the shell's store keeps under it.
|
|
1536
1569
|
|
|
1537
1570
|
A read made while the action opened is **finished**: its answer is in the tree
|
|
1538
1571
|
(and listed in `drawnWith`). The app's own shell is always live for a signed-in
|
|
1539
1572
|
principal — it is the thing that is kept. nova supplies the facts
|
|
1540
1573
|
(`livenessOf`, `@niscorp/nova/reflect`); moss composes the verdict, because
|
|
1541
|
-
the running manifest
|
|
1574
|
+
the running manifest keeps the entries in force, by fingerprint
|
|
1542
1575
|
(`src/shells/snapshot.ts`; the function is not exported, its answer is
|
|
1543
1576
|
`live`, `why` and `drawnWith` on the snapshot). It reads that list and not
|
|
1544
|
-
the cache table, which can
|
|
1545
|
-
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.
|
|
1546
1579
|
|
|
1547
1580
|
When `live` is false the trees are the whole of the screen, and the terminal
|
|
1548
1581
|
opens no socket.
|
|
@@ -1581,26 +1614,26 @@ What it is handed is `DocumentConfig`, and what it answers is `DrawnDocument`.
|
|
|
1581
1614
|
the same node the effect reads it from. Values are escaped.
|
|
1582
1615
|
- **The page's `<head>` is its screen's own.** It is a node in a layout —
|
|
1583
1616
|
nova's `nova:head`, whose children (`nova:title`, `nova:meta`, `nova:link`,
|
|
1584
|
-
`nova:script`) are the elements a head
|
|
1617
|
+
`nova:script`) are the elements a head contains, their props the elements'
|
|
1585
1618
|
attributes. It is in the snapshot's trees like everything else on the screen,
|
|
1586
1619
|
so the elements are read off them and written into the template's `<head>`:
|
|
1587
1620
|
one takes the place of the tag that said the same thing, anything else is
|
|
1588
1621
|
added, and the rest of the head is left as the template has it. `head` in the
|
|
1589
1622
|
result is what was read (`{ elements, actions, refused }`); absent, the
|
|
1590
1623
|
screen has no head and the page went out with the template's. What a head may
|
|
1591
|
-
not
|
|
1624
|
+
not contain — something that runs, or styles — is left out and logged. In the
|
|
1592
1625
|
browser the terminal keeps the page's head on the same node as the screen
|
|
1593
1626
|
moves, and the template's own tags come back when it stops saying them.
|
|
1594
1627
|
- **`site`** is the address the site is served at. With it, every path's
|
|
1595
1628
|
document says its own canonical address (`<link rel="canonical">`, `og:url`).
|
|
1596
1629
|
Without it the template's is left as it is.
|
|
1597
|
-
- **`template`** must
|
|
1630
|
+
- **`template`** must contain the empty root (`root`, default
|
|
1598
1631
|
`<div id="root"></div>`). The screen goes inside it, the snapshot element
|
|
1599
1632
|
straight after. `root` is an empty element written as it stands in the
|
|
1600
1633
|
template, its opening tag and at once its closing tag: any element
|
|
1601
|
-
(`<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
|
|
1602
1635
|
the root, or a root that is not an empty element (an opening tag alone, one
|
|
1603
|
-
that
|
|
1636
|
+
that contains something, one closed in its own tag), has no place for a screen:
|
|
1604
1637
|
the page goes out undrawn (`drawn: false`), and the second case is logged.
|
|
1605
1638
|
- **`server`** is asked three things, and its type says so
|
|
1606
1639
|
(`DocumentConfig['server']`): `principalOf(token)`, `page(path)` and
|
|
@@ -1655,7 +1688,7 @@ paths (`server.executeAs` runs a read the app serves as a charter role), are the
|
|
|
1655
1688
|
caller's.
|
|
1656
1689
|
|
|
1657
1690
|
`renderDocument` is the one way a page is drawn, and its parts are not
|
|
1658
|
-
exported. It reads the session the browser
|
|
1691
|
+
exported. It reads the session the browser keeps off the request's cookie, and
|
|
1659
1692
|
it writes the snapshot into the page as a
|
|
1660
1693
|
`<script type="application/json" id="nisc-snapshot">` element with every `<`
|
|
1661
1694
|
(and U+2028/2029) escaped: a tree carries what people typed, and a path is
|
|
@@ -1678,7 +1711,7 @@ const files: ExportedDocument[] = await exportDocuments({ ...drawing, paths: ['/
|
|
|
1678
1711
|
The `Set-Cookie` values that keep `token` in the browser of the page at this
|
|
1679
1712
|
origin — or, for `null`, take it back. For a sign-in the app answers over HTTP
|
|
1680
1713
|
(a link redeemed, a provider's callback): set them on the response, and the
|
|
1681
|
-
page that follows is signed in having never
|
|
1714
|
+
page that follows is signed in having never had the token.
|
|
1682
1715
|
|
|
1683
1716
|
```typescript
|
|
1684
1717
|
server.get('/login', async (c) => {
|
|
@@ -1727,7 +1760,14 @@ and each one a page built for them, with the payload; every other process is
|
|
|
1727
1760
|
nudged on the same channel, without it. `false`: no shell of theirs lives
|
|
1728
1761
|
here.
|
|
1729
1762
|
|
|
1730
|
-
|
|
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:
|
|
1731
1771
|
|
|
1732
1772
|
- **A reaction is told THAT a write landed, never what it wrote.** No rows.
|
|
1733
1773
|
A receiver that wants the data re-reads it under its own policy — a row
|
|
@@ -1792,7 +1832,7 @@ it answers `undefined`, nothing is minted.
|
|
|
1792
1832
|
`TIDE_DDL` are exported by `@niscorp/tide/postgres`. They were moss's, and do
|
|
1793
1833
|
what they did: see tide's [DOCS.md](../tide/DOCS.md), "The driver" and "The
|
|
1794
1834
|
Postgres store". `createTideStore(runtime.pool, { migrate: false })` takes the
|
|
1795
|
-
pool the runtime
|
|
1835
|
+
pool the runtime keeps, with `TIDE_SEQUENCE` in `runtime.tables`, and its tables
|
|
1796
1836
|
are ordinary tables to moss: migrated by `nisc migrate`, introspected,
|
|
1797
1837
|
grantable, and scoped by a behavior like any other.
|
|
1798
1838
|
|
|
@@ -1818,13 +1858,13 @@ them. The sequences are checked in the one ledgered run, before the feature
|
|
|
1818
1858
|
starts (migrated there under `migrations: 'apply'`), and `migrateTables`
|
|
1819
1859
|
applies them. A feature reads and writes those
|
|
1820
1860
|
tables through vex, as an app does, with entries of its own: they are seeded into a
|
|
1821
|
-
cache of their own,
|
|
1861
|
+
cache of their own, kept by an engine no route is handed, so `/api/vex`
|
|
1822
1862
|
answers `cache_miss` for one of them whatever the charter grants whoever asks,
|
|
1823
1863
|
and no surface lists it. They run under a policy that admits the tables the
|
|
1824
1864
|
feature named as its own and no other, and asks for no principal. An entry
|
|
1825
1865
|
that reads or writes any other table refuses the boot (`moss: the feature "…"
|
|
1826
1866
|
handed over an entry that reads or writes a table that is not its own: "…"`).
|
|
1827
|
-
What another table
|
|
1867
|
+
What another table contains, a feature reads as the app does: through the app's
|
|
1828
1868
|
entries, under the charter. A write by a feature tells the app's engine which
|
|
1829
1869
|
tables changed, so a reactive read over one of them answers again.
|
|
1830
1870
|
|
|
@@ -1838,7 +1878,7 @@ tables changed, so a reactive read over one of them answers again.
|
|
|
1838
1878
|
`server.invalidateIdentity`, `invalidateTag` and `nudge` publish after
|
|
1839
1879
|
applying locally: `invalidate-identity`, `invalidate-tag` and `nudge`. The
|
|
1840
1880
|
fourth, `adopt`, names a principal and tells a process to bring the shells
|
|
1841
|
-
it
|
|
1881
|
+
it keeps for them level with what they are granted now; moss publishes it when a
|
|
1842
1882
|
layout is saved for that principal (`session.artifacts`), and it says
|
|
1843
1883
|
nothing of what was saved. Best-effort:
|
|
1844
1884
|
each targets state that heals on its own clock. Unset, every path behaves as
|
|
@@ -1865,7 +1905,7 @@ tables changed, so a reactive read over one of them answers again.
|
|
|
1865
1905
|
that is unset), and when it has moved it reads again every set of actions
|
|
1866
1906
|
it has a loader for, drops what it had read of what is published for
|
|
1867
1907
|
everybody (the next shell it builds reads that again), runs the check
|
|
1868
|
-
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
|
|
1869
1909
|
policies, the identity records) and has its living shells adopt.
|
|
1870
1910
|
**The pointer carries no set.** It says that something changed, and a
|
|
1871
1911
|
process learns what by reading rows. The only set that has a loader is the
|
|
@@ -1878,7 +1918,7 @@ tables changed, so a reactive read over one of them answers again.
|
|
|
1878
1918
|
what they derived and adopt again.
|
|
1879
1919
|
The row is read and moved through vex, by two
|
|
1880
1920
|
entries of moss's own that no route serves (`src/data/own-entries.ts`);
|
|
1881
|
-
`src/artifactory/generation.ts`
|
|
1921
|
+
`src/artifactory/generation.ts` keeps the clock and no SQL. A move is a compare
|
|
1882
1922
|
and a set: the next number is written where the counter is still what was
|
|
1883
1923
|
read, and read again where it is not. A move a process could not follow is
|
|
1884
1924
|
tried again at every poll until it is followed, and logged when that is
|
|
@@ -1887,13 +1927,13 @@ tables changed, so a reactive read over one of them answers again.
|
|
|
1887
1927
|
has moved on or the reload fails another way, and once when it is followed
|
|
1888
1928
|
(`followed the generation pointer to 4, after 12 looks that failed`). A
|
|
1889
1929
|
reload that fails the same way for an hour is one line, not sixty.
|
|
1890
|
-
- The identity cache — what
|
|
1930
|
+
- The identity cache — what keeps the records `app.identity` resolves. It is
|
|
1891
1931
|
the server's own (`src/identity/cache.ts`) and is not exported. Its limits
|
|
1892
1932
|
are `runtime.identityMax` (default 10,000) and `runtime.identityIdleMs`
|
|
1893
1933
|
(default 30 minutes). At `identityMax` the least recently read record is
|
|
1894
1934
|
dropped to make room, and whoever it was is resolved again on their next
|
|
1895
1935
|
request. A record is forgotten with `server.invalidateIdentity`,
|
|
1896
|
-
`invalidateTag` and `refresh`, and what is
|
|
1936
|
+
`invalidateTag` and `refresh`, and what is kept is read through
|
|
1897
1937
|
`server.identities`.
|
|
1898
1938
|
|
|
1899
1939
|
### Telemetry
|
|
@@ -1911,13 +1951,13 @@ with `integrations/` and whose `hasPrincipal` is `false`. The generation
|
|
|
1911
1951
|
counter's poll emits none. A `socket.upgrade` is `ok` (admitted), `refused` (the token
|
|
1912
1952
|
offered is nobody's, or no place is left for a shell for nobody) or
|
|
1913
1953
|
`error` (the session could not be opened: the verifier
|
|
1914
|
-
threw, what somebody
|
|
1954
|
+
threw, what somebody is granted could not be asked, their shell could not be built).
|
|
1915
1955
|
A `socket.close` span runs from the upgrade to the close.
|
|
1916
1956
|
`emit` is never awaited, and a sink that throws costs the caller nothing: the
|
|
1917
1957
|
throw is caught where the span is emitted, and logged.
|
|
1918
1958
|
|
|
1919
1959
|
`refused` is a no the server gave (a policy, a limit, an integration that is
|
|
1920
|
-
not installed): an outcome, and not a fault. `attributes`
|
|
1960
|
+
not installed): an outcome, and not a fault. `attributes` contains identifiers
|
|
1921
1961
|
and measurements (a fingerprint, a count, a status) and never a payload, a
|
|
1922
1962
|
row or who a principal is: a principal is there only as `hasPrincipal`. Moss
|
|
1923
1963
|
sets none of `traceId`, `spanId` and `parentSpanId`.
|
|
@@ -1932,7 +1972,7 @@ const telemetry: Telemetry = { emit: (span) => void spans.push(span) };
|
|
|
1932
1972
|
|
|
1933
1973
|
### Resolution
|
|
1934
1974
|
|
|
1935
|
-
Who somebody is, what they
|
|
1975
|
+
Who somebody is, what they are granted and what they may read and write are asked of
|
|
1936
1976
|
the server, which resolves a principal the way a request does (the `identity`
|
|
1937
1977
|
seam, or `assignments`): `(await server.identity(principal)).roles`,
|
|
1938
1978
|
`server.catalogOf(principal)`, `server.policyForRoles(roles)`. Nothing is
|
|
@@ -1952,7 +1992,7 @@ app that resolves people through `identity`.
|
|
|
1952
1992
|
- An entry that declares a `reach` (vex) is served under the same roles'
|
|
1953
1993
|
grants recompiled at that named profile. The vex surfaces and `executeAs` do
|
|
1954
1994
|
it themselves; it narrows rows, never widens verbs.
|
|
1955
|
-
- 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
|
|
1956
1996
|
action's layout where a shell is built, in the shell's layout store.
|
|
1957
1997
|
Nothing answers the variants by themselves.
|
|
1958
1998
|
- `verifyApp(app, grants)` — the check boot runs, for an app
|
|
@@ -1964,7 +2004,8 @@ app that resolves people through `identity`.
|
|
|
1964
2004
|
report is `{ errors, said, charter }`: `errors` is `{ check, detail }[]`,
|
|
1965
2005
|
`check` one of `'actions'` (a definition nova's schema does not read),
|
|
1966
2006
|
`'charter'`, `'reach'` and `'variants'`; `said` is what a boot only says (a
|
|
1967
|
-
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
|
|
1968
2009
|
report. A boot refuses on `errors`. A running server answers for what is in
|
|
1969
2010
|
force with `server.charterReport()`. It verifies and does nothing else: what
|
|
1970
2011
|
it is handed is not read by the manifest's schema and is not frozen.
|
|
@@ -1995,7 +2036,7 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
|
|
|
1995
2036
|
is not exported). It is handed no manifest and no
|
|
1996
2037
|
runtime, but a typed object of what it needs: one function that answers what
|
|
1997
2038
|
a principal's shell is made of (who they are, the action definitions they
|
|
1998
|
-
|
|
2039
|
+
are granted, the canvases and the frame, each naming its layout in the layout
|
|
1999
2040
|
store, the layout store's seed with those layouts in it (for an action the
|
|
2000
2041
|
published one over the build's, their roles' layout variant over that, and
|
|
2001
2042
|
over it the layout of their own they marked in use), the
|
|
@@ -2008,11 +2049,11 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
|
|
|
2008
2049
|
reach a shell through that one answer, and the server's wiring reads none
|
|
2009
2050
|
of them off the app. For an entry that is what a shell is told of the reads
|
|
2010
2051
|
on its screens. What a read replays the engine asks the running manifest
|
|
2011
|
-
for too (see "Where the app's entries are
|
|
2052
|
+
for too (see "Where the app's entries are kept", under `createServer`).
|
|
2012
2053
|
A kept shell may sit unattached for
|
|
2013
2054
|
`runtime.shellIdleMs` (default 30 minutes; `0` disables the sweep). A shell
|
|
2014
2055
|
that is not kept (nobody signed in; any shell of a page's host) ends when
|
|
2015
|
-
its last terminal leaves, and the host
|
|
2056
|
+
its last terminal leaves, and the host keeps nothing of a shell that has
|
|
2016
2057
|
ended.
|
|
2017
2058
|
- `session(token, principal, options?)` — `options = { seed?, inputs? }`;
|
|
2018
2059
|
`snapshot` is described under [The document](#the-document), and what it
|
|
@@ -2030,13 +2071,13 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
|
|
|
2030
2071
|
so that a change can reach it. The socket ends it when the connection
|
|
2031
2072
|
closes. Code that opens one in process and attaches nothing ends it
|
|
2032
2073
|
itself, with `session.detach(connection)` (any connection: none was
|
|
2033
|
-
attached); until then the host
|
|
2074
|
+
attached); until then the host keeps the shell.
|
|
2034
2075
|
- A host has no `adopt` and no `stop`. Each was a second way, for one
|
|
2035
2076
|
host, to something a server does for all of them at once.
|
|
2036
2077
|
**A change is the server's.** When what the app consists of changes
|
|
2037
2078
|
(`server.refresh()`, `server.replaceActions()`, `server.replaceEntries()`, an integration approved
|
|
2038
2079
|
or removed, a change another process made), every living shell of every
|
|
2039
|
-
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
|
|
2040
2081
|
place. Every living shell: the ones a host keeps, and the ones it built
|
|
2041
2082
|
for one connection, which for the app's host is each visitor's and for a
|
|
2042
2083
|
page's host is everybody's. Definitions that arrived or changed are
|
|
@@ -2054,13 +2095,13 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
|
|
|
2054
2095
|
it. The canvases a shell's manifest declares, and what is mounted on any
|
|
2055
2096
|
canvas, are the shell's own state and are not taken again: a reset builds
|
|
2056
2097
|
that afresh. A canvas the manifest does not declare, that a layout in
|
|
2057
|
-
force
|
|
2058
|
-
it, once no layout
|
|
2059
|
-
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.
|
|
2060
2101
|
Each shell adopts on its own: one whose principal is never answered (an
|
|
2061
|
-
`identity` that hangs for them)
|
|
2102
|
+
`identity` that hangs for them) delays no other. So a change asks about
|
|
2062
2103
|
every living shell in the same moment, and an app's `identity` runs at
|
|
2063
|
-
once for every signed-in principal whose record is not
|
|
2104
|
+
once for every signed-in principal whose record is not kept.
|
|
2064
2105
|
A shell whose build was under way adopts when it lands, and so does one a
|
|
2065
2106
|
reset was replacing; no change waits for a build, or for another change.
|
|
2066
2107
|
One built for the length of a `snapshot` is read and ended, and adopts
|
|
@@ -2074,7 +2115,9 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
|
|
|
2074
2115
|
it built for each of their connections.) `false` = they have no living
|
|
2075
2116
|
shell in this host; nothing is built. This host, in this process: it
|
|
2076
2117
|
reaches no page's shell and no other process. To tell somebody's screens
|
|
2077
|
-
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.
|
|
2078
2121
|
- `list()` — every durable shell alive right now, each as
|
|
2079
2122
|
`{ principal, connections, since, idleSince, canvases }`. moss owns the map,
|
|
2080
2123
|
so moss enumerates it; an app keeping its own note beside it can only drift.
|
|
@@ -2089,7 +2132,7 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
|
|
|
2089
2132
|
Every living shell of theirs on this host: the one it keeps for them, or,
|
|
2090
2133
|
on a host that keeps none (a page's), the one built for each of their
|
|
2091
2134
|
connections, each replaced for itself.
|
|
2092
|
-
`false` = they
|
|
2135
|
+
`false` = they have no shell, which is an answer, not an error. The
|
|
2093
2136
|
replacement is built from what the shell was opened with (for a page's,
|
|
2094
2137
|
the inputs of its path and its id seed), and a shell's resets run one
|
|
2095
2138
|
after another. A reset that arrives while another waits for its turn is
|
|
@@ -2106,9 +2149,9 @@ for (const error of report.errors) console.error(`${error.check}: ${error.detail
|
|
|
2106
2149
|
remote clients ride `attach`/`dispatch`. Nine members of `shell` throw, as
|
|
2107
2150
|
on [`FunctionSession`](#functionsession): the whole shell is
|
|
2108
2151
|
`unverifiedShell(session)`. `shell` is a **getter** — `reset`
|
|
2109
|
-
replaces the shell under a session already
|
|
2152
|
+
replaces the shell under a session already handed out, so a snapshot of the field
|
|
2110
2153
|
would go on addressing the disposed one.
|
|
2111
|
-
`dispatch(canvas, event)`
|
|
2154
|
+
`dispatch(canvas, event)` checks what a terminal sent to the shell: the
|
|
2112
2155
|
canvas must be one the shell has, an `origin` the event names must be an
|
|
2113
2156
|
instance on that canvas (with none, the canvas's active instance is
|
|
2114
2157
|
stamped), and the event must parse as one of nova's (`NovaEventSchema`:
|
|
@@ -2157,7 +2200,7 @@ server.nudge('usr_ada', 'notes-changed');
|
|
|
2157
2200
|
transport: `server.socket(url, connection)`. `server.socket.stop()` ends
|
|
2158
2201
|
revalidation (the timer is unref'd, so a plain process needn't call it).
|
|
2159
2202
|
`createServer` builds it (`src/socket/`), handed who a token is, what
|
|
2160
|
-
somebody
|
|
2203
|
+
somebody is granted, and where a session comes from for the app and for each
|
|
2161
2204
|
page. Neither its factory nor its type is exported by name: the type is
|
|
2162
2205
|
`MossServer['socket']`.
|
|
2163
2206
|
- **Identity is asked twice.** At upgrade, and then every
|
|
@@ -2166,15 +2209,28 @@ server.nudge('usr_ada', 'notes-changed');
|
|
|
2166
2209
|
somebody else — gets an `invalid_token` error frame and a `4401` close, which
|
|
2167
2210
|
is the recovery the terminal already performs: drop the token, reconnect
|
|
2168
2211
|
anonymous, land on the served lock screen.
|
|
2169
|
-
- Anonymous connections are never revalidated: nothing they
|
|
2212
|
+
- Anonymous connections are never revalidated: nothing they have can expire.
|
|
2170
2213
|
- A verifier that **throws** is a fault, not a sign-out — the connection is
|
|
2171
2214
|
left alone and asked again next pass, so a database blip cannot become an
|
|
2172
2215
|
outage. Only an explicit `null` (or a changed principal) closes. That it
|
|
2173
2216
|
threw is logged, once for a pass: how many connections could not be asked
|
|
2174
2217
|
about, and the first error.
|
|
2175
|
-
- One pass at a time: a pass asks
|
|
2176
|
-
|
|
2177
|
-
|
|
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.
|
|
2178
2234
|
- Without this the socket was the asymmetry: the HTTP surfaces re-ask on
|
|
2179
2235
|
every request, so an expired credential left the socket open and rendering
|
|
2180
2236
|
while every endpoint the server shell called came back 401 — a live
|
|
@@ -2185,7 +2241,7 @@ server.nudge('usr_ada', 'notes-changed');
|
|
|
2185
2241
|
catalog asked, its shell built) is not attached to a shell, so a kept shell
|
|
2186
2242
|
idles and one built for that connection alone is disposed. The type also
|
|
2187
2243
|
has `upgrade` (below) and `seal`. `seal` is set by the socket, on a
|
|
2188
|
-
connection whose browser
|
|
2244
|
+
connection whose browser has a seal: a transport leaves it out.
|
|
2189
2245
|
- `ServerMessage` (`@niscorp/moss/protocol`) — what the server sends: `hello | catalog | frame | render |
|
|
2190
2246
|
render-delta | session | pong | error`.
|
|
2191
2247
|
- What a terminal sends is `event | publish | resync | reset | back | popTo | ping`,
|
|
@@ -2222,7 +2278,7 @@ server.nudge('usr_ada', 'notes-changed');
|
|
|
2222
2278
|
protocol-level, not app-level — no action declares it and no charter grants
|
|
2223
2279
|
it — and it is answered by the frames it produces, not by an envelope of its
|
|
2224
2280
|
own. Any terminal may send it, signed in or not, and each one that is acted
|
|
2225
|
-
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
|
|
2226
2282
|
`inputs`, `phrases`, `functions` and `seeds`. Resets that arrive while one
|
|
2227
2283
|
waits for its turn are answered by it (`reset(principal)`, under `shells`),
|
|
2228
2284
|
so a burst costs two builds at most. Nothing limits how often: a terminal
|
|
@@ -2251,7 +2307,7 @@ server.nudge('usr_ada', 'notes-changed');
|
|
|
2251
2307
|
- `4503`: the server is serving as many terminals with nobody signed in as
|
|
2252
2308
|
`runtime.anonymousShellMax` allows, and built no shell for this one. An
|
|
2253
2309
|
`at_capacity` error frame, then the close. Not a recovery: the terminal
|
|
2254
|
-
keeps what it
|
|
2310
|
+
keeps what it has and reconnects with its usual backoff, which grows
|
|
2255
2311
|
for as long as it is refused.
|
|
2256
2312
|
- `4426`: the two ends speak protocols the other cannot (below).
|
|
2257
2313
|
- `error` codes: `invalid_token`, `session_failed`, `at_capacity`,
|
|
@@ -2267,7 +2323,7 @@ server.nudge('usr_ada', 'notes-changed');
|
|
|
2267
2323
|
- **Who a terminal is** is decided on the upgrade request, from a header of
|
|
2268
2324
|
it — never from its address, which is what every proxy on the way writes
|
|
2269
2325
|
into its log. A terminal offers the subprotocol `nisc`, and beside it its
|
|
2270
|
-
token when it
|
|
2326
|
+
token when it has one: `offerToken(token | null)` returns the list to
|
|
2271
2327
|
construct the socket with (`new WebSocket(url, offerToken(token))`), and the
|
|
2272
2328
|
server answers `nisc`. A token in the address (`?token=`) is not read. A
|
|
2273
2329
|
transport hands the offer over as `connection.upgrade.offered`
|
|
@@ -2276,14 +2332,16 @@ server.nudge('usr_ada', 'notes-changed');
|
|
|
2276
2332
|
- **A browser on the app's own page** is who its session cookie says
|
|
2277
2333
|
([`sessionCookies`](#sessioncookiespage-token-options)). The cookie is read
|
|
2278
2334
|
only when the upgrade's `Origin` is the host it was addressed to, or one
|
|
2279
|
-
`runtime.origins` lists.
|
|
2280
|
-
|
|
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,
|
|
2281
2339
|
as before, and moss says so once in the log.) A token such a page offers is who it is and is
|
|
2282
2340
|
moved into the cookie by the answer to the upgrade; one that no longer
|
|
2283
2341
|
resolves is nobody (served, not refused) and is taken back. `?key=` names
|
|
2284
2342
|
which of the browser's sessions the terminal is — a seat; the cookie is named
|
|
2285
2343
|
by it. `?leave=1` is a terminal that was signed out: it is nobody whatever
|
|
2286
|
-
its browser
|
|
2344
|
+
its browser has, and the cookie is taken back. A transport passes what the
|
|
2287
2345
|
request carried as `connection.upgrade` — `{ offered, origin, host, cookie }`
|
|
2288
2346
|
— and, when it has not answered the request yet, `answer(cookies)`: moss
|
|
2289
2347
|
calls it once who is asking is decided, with the `Set-Cookie` values to
|
|
@@ -2373,12 +2431,12 @@ through the object form — when connection count matters more than bandwidth.
|
|
|
2373
2431
|
An object is handed to `ws` verbatim; see its `perMessageDeflate` options.
|
|
2374
2432
|
|
|
2375
2433
|
The setting is the Node transport's, and the server's socket carries it there
|
|
2376
|
-
from the runtime: it
|
|
2434
|
+
from the runtime: it applies under `serve`, `nisc start`, the dev plugin, and a
|
|
2377
2435
|
host that attaches `server.socket` itself.
|
|
2378
2436
|
|
|
2379
2437
|
#### Frame deltas — `runtime.shellFrameDelta`, default **off**
|
|
2380
2438
|
|
|
2381
|
-
A changed canvas, described against the frame that connection already
|
|
2439
|
+
A changed canvas, described against the frame that connection already has:
|
|
2382
2440
|
copy runs from the old frame plus literal inserts, checksummed.
|
|
2383
2441
|
|
|
2384
2442
|
```typescript
|
|
@@ -2398,7 +2456,7 @@ the same shell, in the same pass. The two kinds of connection coexist.
|
|
|
2398
2456
|
**A canvas whose frame is over 64 KB is always sent whole.** Comparing two
|
|
2399
2457
|
frames costs the server in proportion to their size, not to what changed, and
|
|
2400
2458
|
it does that work on the thread every session shares — about 7 ms at 64 KB, a
|
|
2401
|
-
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,
|
|
2402
2460
|
is longer than 64 KB, the server does not compare them. It is not a setting.
|
|
2403
2461
|
|
|
2404
2462
|
What it buys, measured on Lyra:
|
|
@@ -2462,7 +2520,7 @@ Correctness, which matters more than the saving:
|
|
|
2462
2520
|
first; this is the catch-all. `owned` (default: moss's own prefixes) names
|
|
2463
2521
|
what is never a page — an unknown path under one is a 404, not a screen. So is
|
|
2464
2522
|
a **missing file**: a name with an extension that is neither a file in `dist`
|
|
2465
|
-
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
|
|
2466
2524
|
before a deploy asks for its script by the old name, and needs "gone" back,
|
|
2467
2525
|
not a document). A page's own path may have a dot in it (`/docs/v1.2`).
|
|
2468
2526
|
What a browser may keep of these files, and compressing what goes out, is not
|
|
@@ -2505,7 +2563,12 @@ Requires the optional `vite` peer.
|
|
|
2505
2563
|
(`renderDocument`); `MOSS_PATHS` go to the app server; the rest is vite's.
|
|
2506
2564
|
An edit under a watched path re-boots the whole app and reloads the page;
|
|
2507
2565
|
the outgoing server answers until the new one is up, and a failed re-boot
|
|
2508
|
-
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
|
|
2509
2572
|
a terminal that is not a page connects again, to the app that is booted.
|
|
2510
2573
|
- `options.app(load): Promise<DevApp>` — stand the app up. `load` is vite's
|
|
2511
2574
|
`ssrLoadModule`. `DevApp = { server, close?, draw?, htmlAttributes?,
|
|
@@ -2517,9 +2580,15 @@ Requires the optional `vite` peer.
|
|
|
2517
2580
|
end of the request's socket is loopback (`127.0.0.0/8`, `::1`, or either
|
|
2518
2581
|
written as an IPv4-mapped IPv6 address). Any other request is answered
|
|
2519
2582
|
`403` with a sentence that says why, and the app is not asked. What a
|
|
2520
|
-
header says of where a request came from (`X-Forwarded-For`)
|
|
2521
|
-
behind a proxy on the same machine every request is the proxy's,
|
|
2522
|
-
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.
|
|
2523
2592
|
- `signInFromNetwork?: boolean` (default `false`) answers the sign-in to
|
|
2524
2593
|
every device that can reach the dev server, for trying a signed-in screen
|
|
2525
2594
|
on a phone. It hands out a session for whoever the address names: with it
|
|
@@ -2626,7 +2695,7 @@ vocabulary, and the app that has it defines it.
|
|
|
2626
2695
|
|
|
2627
2696
|
`check` and `prepare` are handed, as `bundle` (`ExtensionContext`), what moss
|
|
2628
2697
|
knows of the bundle: `integration` (its id), `url` (where its service
|
|
2629
|
-
lives), `actions` (its action definitions, each already
|
|
2698
|
+
lives), `actions` (its action definitions, each already checked against its
|
|
2630
2699
|
namespace, its endpoints and the kit), `fingerprints` (the ones the app
|
|
2631
2700
|
serves), and `layoutMisfits(layout)` (each place a layout does not fit the
|
|
2632
2701
|
app's kit, for a vocabulary that lets a bundle carry one).
|
|
@@ -2635,7 +2704,7 @@ vocabulary, and the app that has it defines it.
|
|
|
2635
2704
|
"console.log(require('node:crypto').randomBytes(32).toString('base64'))"`).
|
|
2636
2705
|
With none, a keypair is made when the feature starts and kept nowhere, so
|
|
2637
2706
|
each boot and each process has its own. Give one where an integration's
|
|
2638
|
-
service
|
|
2707
|
+
service keeps the public half in its environment, or where a deployment
|
|
2639
2708
|
runs more than one process: the same seed is the same key everywhere. It is
|
|
2640
2709
|
this feature's setting and no other feature is handed it. One that decodes
|
|
2641
2710
|
to fewer than 32 bytes refuses the boot.
|
|
@@ -2665,14 +2734,14 @@ that:
|
|
|
2665
2734
|
- `listIntegrations(): Promise<RegisteredIntegration<Extension>[]>` — every
|
|
2666
2735
|
registered integration, in the order of the ids: `{ id, status, url,
|
|
2667
2736
|
extension }`. `status` is `'pending'` or `'approved'`; `extension` is what
|
|
2668
|
-
the row
|
|
2737
|
+
the row stores, read by the app's schema and so typed by it (`undefined`: the
|
|
2669
2738
|
bundle carried none, the app supplied no schema, or the schema no longer
|
|
2670
2739
|
reads what was stored, which is logged with the integration's id). An app
|
|
2671
2740
|
builds its placements, its listing and anything else from this.
|
|
2672
2741
|
- `callIntegration(id, path, { principal, method?, body?, scope? }):
|
|
2673
2742
|
Promise<Response>` — call an installed integration when
|
|
2674
2743
|
nobody is driving; throws unless it is approved and installed for the
|
|
2675
|
-
principal's tenant. It is not
|
|
2744
|
+
principal's tenant. It is not checked against the integration's reach: an app calls
|
|
2676
2745
|
an endpoint its own vocabulary names (a preview, a page it mounts on a route
|
|
2677
2746
|
of its own) with this. `principal` is who the call is made for, and who the
|
|
2678
2747
|
assertion names. `method` defaults to `POST`; `body` is sent as JSON;
|
|
@@ -2693,7 +2762,7 @@ for everybody, and an empty list is none.
|
|
|
2693
2762
|
The rule that reads it is this feature's (an
|
|
2694
2763
|
`ext.<audience>.<integration>.<name>` action is there for somebody only where
|
|
2695
2764
|
that integration is in their list), and it is laid when the feature starts:
|
|
2696
|
-
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
|
|
2697
2766
|
of its own wherever the charter grants it.
|
|
2698
2767
|
|
|
2699
2768
|
What the feature serves once it is started:
|
|
@@ -2706,10 +2775,10 @@ What the feature serves once it is started:
|
|
|
2706
2775
|
|
|
2707
2776
|
A bearer token with the `ik_` prefix is an integration key: it is resolved to
|
|
2708
2777
|
the integration it was issued to and, through `integrationActor`, to a
|
|
2709
|
-
principal (`401` unknown key, `403` no actor). No two integrations
|
|
2778
|
+
principal (`401` unknown key, `403` no actor). No two integrations have the
|
|
2710
2779
|
hash of one key (a unique index on `integrations.key_hash`).
|
|
2711
2780
|
|
|
2712
|
-
**What intake
|
|
2781
|
+
**What intake checks a bundle against**, before any of it is kept. It is upgraded by
|
|
2713
2782
|
its grammar stamps and read by the bundle's schema. Each action is named
|
|
2714
2783
|
`ext.<audience>.<integration>.<name>` under the integration's own id; each of
|
|
2715
2784
|
its endpoints is a fingerprint the app serves, called on one of the app's vex
|
|
@@ -2721,7 +2790,7 @@ routed: a `..`, `.`, `%2e` or `\` that would move it is refused, and so is a
|
|
|
2721
2790
|
`{{…}}` template, which is filled in when the endpoint is called; one in the
|
|
2722
2791
|
query is taken. Its layout composes what the app's kit has; and no
|
|
2723
2792
|
chain of its steps, laid over the app's own actions, runs for ever. Then
|
|
2724
|
-
`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
|
|
2725
2794
|
reason, moss's and the app's, is reported together, and any one refuses the
|
|
2726
2795
|
bundle whole: the last good import keeps serving.
|
|
2727
2796
|
|
|
@@ -2734,7 +2803,7 @@ bundle whole: the last good import keeps serving.
|
|
|
2734
2803
|
its actions in place of the ones it shipped before, and the hash of its key
|
|
2735
2804
|
on the import a key is issued with. It lands whole, or the import before it
|
|
2736
2805
|
is still there, whole. The answer carries `key` once, on the registration
|
|
2737
|
-
whose key the row
|
|
2806
|
+
whose key the row stores: the hash is written where the row has none, so of
|
|
2738
2807
|
two registrations of one new integration in the same moment one is answered
|
|
2739
2808
|
the key and the other is answered as a later import is, with none.
|
|
2740
2809
|
- *Approve* (`POST /operator/integrations/:id/approve`) reads what the
|
|
@@ -2760,12 +2829,23 @@ bundle whole: the last good import keeps serving.
|
|
|
2760
2829
|
- *The proxy* (`/integrations/:id/*`) forwards a signed-in caller's call to an
|
|
2761
2830
|
approved integration that is installed for them, with an assertion that
|
|
2762
2831
|
says who they are. It forwards the paths the integration's actions declare
|
|
2763
|
-
as endpoints, each for whoever
|
|
2832
|
+
as endpoints, each for whoever is granted an action that declares it, and
|
|
2764
2833
|
answers `404` for any other path.
|
|
2765
2834
|
- *A webhook* (`POST /integrations/:id/hook/*`) takes no session and no
|
|
2766
2835
|
assertion is minted for it: the body goes on to the integration's service
|
|
2767
|
-
byte for byte,
|
|
2768
|
-
|
|
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
|
|
2769
2849
|
that is unknown or not approved answers `404`. **The door has a limit, and
|
|
2770
2850
|
it is a limit per process**: 240 calls a minute for each integration,
|
|
2771
2851
|
counted in the memory of the process that takes them, in windows of a minute
|
|
@@ -2776,6 +2856,17 @@ bundle whole: the last good import keeps serving.
|
|
|
2776
2856
|
a process that restarts counts from nothing. It is not a ceiling for the
|
|
2777
2857
|
deployment, and neither number is a setting: a deployment that needs one
|
|
2778
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.
|
|
2779
2870
|
|
|
2780
2871
|
**A vendor's own page inside the app** is the app's to mount. Moss frames
|
|
2781
2872
|
none: an app that wants one serves a route of its own (`routes(server)` in
|
|
@@ -2799,12 +2890,12 @@ app's own vex entry reads `integrations.extension` as it reads any column.
|
|
|
2799
2890
|
| `extension` | what its bundle said in the app's own vocabulary, as the app's `prepare` answered it |
|
|
2800
2891
|
| `last_import_at`, `last_error` | when the last good import landed, and why the last one did not |
|
|
2801
2892
|
|
|
2802
|
-
`integration_actions`
|
|
2893
|
+
`integration_actions` has one row for each action: `integration_id`,
|
|
2803
2894
|
`action_id`, `definition`, and `grammar`, the stamps the definition is written
|
|
2804
2895
|
at.
|
|
2805
2896
|
|
|
2806
2897
|
The feature reads and writes them through vex, with entries of its own that no
|
|
2807
|
-
route serves (see [Features](#features)); it
|
|
2898
|
+
route serves (see [Features](#features)); it contains no SQL. Landing a bundle is
|
|
2808
2899
|
a batch, so `runtime.db` has to have `transaction`, as it does for any batch an
|
|
2809
2900
|
app writes.
|
|
2810
2901
|
|
|
@@ -2834,7 +2925,7 @@ const approved = async (): Promise<RegisteredIntegration<Listing>[]> => (await i
|
|
|
2834
2925
|
|
|
2835
2926
|
`{ verifyKey, mint(claims, ttlMs?) }` — the ed25519 assertion the feature signs
|
|
2836
2927
|
every call to an integration with, for a check or a service in the same
|
|
2837
|
-
workspace that wants to mint or
|
|
2928
|
+
workspace that wants to mint or keep one. An integration verifies it against
|
|
2838
2929
|
`GET /api/integrations/verify-key`.
|
|
2839
2930
|
|
|
2840
2931
|
`seed` is 32 bytes as base64, and makes the same keypair wherever it is given:
|
|
@@ -2946,7 +3037,7 @@ goes around moss: see [`FunctionSession`](#functionsession).
|
|
|
2946
3037
|
- `initial` — pass what `readDocumentSnapshot()` returned. The wire starts from
|
|
2947
3038
|
it instead of from nothing, so the first render matches the page's HTML and
|
|
2948
3039
|
the first frames off the socket confirm it. It is used only when it was drawn
|
|
2949
|
-
for who this terminal is — signed in and
|
|
3040
|
+
for who this terminal is — signed in and with a token, or neither;
|
|
2950
3041
|
anything else is somebody else's screen and the wire starts empty. Its `seed`
|
|
2951
3042
|
is named on the first connect only. Its `path` is named on every connect
|
|
2952
3043
|
(`config.path` overrides it; a page that was not drawn on the server passes
|
|
@@ -2992,7 +3083,7 @@ is the same recovery a layer down. It is also the way out of `incompatible`,
|
|
|
2992
3083
|
once the server has been updated: the connection it makes is found compatible
|
|
2993
3084
|
or not on its own account, and is retried like any other when it drops.
|
|
2994
3085
|
|
|
2995
|
-
**The wire
|
|
3086
|
+
**The wire has one socket at a time.** Before it makes one it lets go of the
|
|
2996
3087
|
one it had: its handlers come off and it is closed. That one may have closed
|
|
2997
3088
|
already, may have carried another principal, or may be a connect still in
|
|
2998
3089
|
flight when `reset()` was called; whichever, nothing it says afterwards is
|
|
@@ -3047,7 +3138,7 @@ one pressed once the connection is open drops them and is sent, because it was
|
|
|
3047
3138
|
pressed on the screen the person sees now. `publish`, `back` and `popTo` name
|
|
3048
3139
|
no canvas to check against, and are dropped unless the connection is open.
|
|
3049
3140
|
|
|
3050
|
-
`back()` sends `{ type: 'back' }` and nothing else — no location is
|
|
3141
|
+
`back()` sends `{ type: 'back' }` and nothing else — no location is kept here,
|
|
3051
3142
|
so what comes back is whatever canvases moved, over the same stream every other
|
|
3052
3143
|
change arrives on. It is dropped on a closed socket rather than queued: a back
|
|
3053
3144
|
pressed during an outage is about a screen the person is no longer being served,
|
|
@@ -3120,7 +3211,7 @@ in the subpaths.
|
|
|
3120
3211
|
status.
|
|
3121
3212
|
|
|
3122
3213
|
**The connection's status reaches every target, the same way.** When a
|
|
3123
|
-
connection drops, the trees the terminal
|
|
3214
|
+
connection drops, the trees the terminal has stay on screen: a reconnect
|
|
3124
3215
|
re-sends the current ones, and blanking in between would show a working app as
|
|
3125
3216
|
an empty one. So a screen left up by a dead socket looks exactly like a live
|
|
3126
3217
|
one, and every target is told which it is: `api.status()` is `'connecting' |
|
|
@@ -3170,7 +3261,7 @@ Requires the optional `react`/`react-dom` peers.
|
|
|
3170
3261
|
SlotWrapper. Served trees carry identity only, so its props
|
|
3171
3262
|
(`TerminalSlotWrapperProps`) are `{ canvasId, instanceId, definitionId }`
|
|
3172
3263
|
and the content as `children` — `definitionId`, not `action`.
|
|
3173
|
-
- **Adoption.** A `root` that already
|
|
3264
|
+
- **Adoption.** A `root` that already contains elements, on a wire that has a
|
|
3174
3265
|
frame, was drawn on the server from the snapshot the wire started from: the
|
|
3175
3266
|
target adopts those elements (`hydrateRoot`) instead of replacing them. An
|
|
3176
3267
|
empty root, or a wire with no frame (the page was drawn for somebody else),
|
|
@@ -3187,7 +3278,7 @@ Requires the optional `react`/`react-dom` peers.
|
|
|
3187
3278
|
one. It is drawn with the status the page's terminal starts in: `'static'`
|
|
3188
3279
|
when `live` is `false` (no socket is opened for that page), `'connecting'`
|
|
3189
3280
|
otherwise. So a kit component that draws the status draws the same thing on
|
|
3190
|
-
both sides. The same
|
|
3281
|
+
both sides. The same applies to the Vue entry below.
|
|
3191
3282
|
|
|
3192
3283
|
**What a kit owes a server-drawn page.** The first pass in the browser must
|
|
3193
3284
|
draw exactly what the server drew, so nothing that differs between the two may
|
|
@@ -3201,7 +3292,7 @@ decide a component's first render:
|
|
|
3201
3292
|
- What a component puts on `<html>` from an effect is not in the page until the
|
|
3202
3293
|
script runs; give it to `renderDocument`'s `htmlAttributes`.
|
|
3203
3294
|
|
|
3204
|
-
An app
|
|
3295
|
+
An app guards this with a check: draw the page, open it in a DOM with the real
|
|
3205
3296
|
wire and target, and assert React said nothing (atrium's and lyra's `ssr-check`).
|
|
3206
3297
|
|
|
3207
3298
|
## `@niscorp/moss/terminal/vue`
|
|
@@ -3223,7 +3314,7 @@ Requires the optional `vue` peer.
|
|
|
3223
3314
|
- `TerminalSlotWrapper` — a Vue component wrapping each action instance at
|
|
3224
3315
|
the `ActionSlot` boundary, handed `{ canvasId, instanceId, definitionId }`
|
|
3225
3316
|
as props (`TerminalSlotWrapperProps`) and the content as its default slot.
|
|
3226
|
-
- **Adoption**, as the react target: a root that
|
|
3317
|
+
- **Adoption**, as the react target: a root that contains server-drawn elements,
|
|
3227
3318
|
on a wire with a frame, is mounted with `createSSRApp` and adopted.
|
|
3228
3319
|
|
|
3229
3320
|
### `@niscorp/moss/terminal/vue/server`
|