@niscorp/moss 0.3.2 → 0.3.3
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 +102 -0
- package/DESIGN.md +84 -19
- package/DOCS.md +170 -35
- package/README.md +2 -2
- package/dist/{chunk-J72N3EMJ.js → chunk-4T6KAXBP.js} +45 -27
- package/dist/chunk-4T6KAXBP.js.map +1 -0
- package/dist/{chunk-ZP3C53AC.js → chunk-AUZMT3GL.js} +739 -654
- package/dist/chunk-AUZMT3GL.js.map +1 -0
- package/dist/{chunk-ZOEUEMDX.js → chunk-HOZID4EM.js} +131 -16
- package/dist/chunk-HOZID4EM.js.map +1 -0
- package/dist/chunk-NE2EXMTO.js +103 -0
- package/dist/chunk-NE2EXMTO.js.map +1 -0
- package/dist/client/node.cjs +1 -1
- package/dist/client/node.cjs.map +1 -1
- package/dist/client/node.js +1 -1
- package/dist/client/node.js.map +1 -1
- package/dist/client.cjs +60 -26
- package/dist/client.cjs.map +1 -1
- package/dist/client.d.cts +6 -1
- package/dist/client.d.ts +6 -1
- package/dist/client.js +2 -2
- package/dist/{document-D9khv9jI.d.cts → document-DhWxieUc.d.cts} +22 -3
- package/dist/{document-D9khv9jI.d.ts → document-DhWxieUc.d.ts} +22 -3
- package/dist/index.cjs +777 -572
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +19 -3
- package/dist/index.d.ts +19 -3
- package/dist/index.js +2 -2
- package/dist/node.cjs +370 -219
- package/dist/node.cjs.map +1 -1
- package/dist/node.d.cts +2 -1
- package/dist/node.d.ts +2 -1
- package/dist/node.js +3 -3
- package/dist/terminal/index.cjs +60 -26
- package/dist/terminal/index.cjs.map +1 -1
- package/dist/terminal/index.js +2 -2
- package/dist/vite.cjs +103 -28
- package/dist/vite.cjs.map +1 -1
- package/dist/vite.d.cts +1 -1
- package/dist/vite.d.ts +1 -1
- package/dist/vite.js +14 -9
- package/dist/vite.js.map +1 -1
- package/package.json +9 -9
- package/dist/chunk-J72N3EMJ.js.map +0 -1
- package/dist/chunk-SUVDISEG.js +0 -64
- package/dist/chunk-SUVDISEG.js.map +0 -1
- package/dist/chunk-ZOEUEMDX.js.map +0 -1
- package/dist/chunk-ZP3C53AC.js.map +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,107 @@
|
|
|
1
1
|
# @niscorp/moss
|
|
2
2
|
|
|
3
|
+
## 0.3.3
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- 78a563f: A page served by its app no longer holds its session: the browser does, in a cookie no script can read.
|
|
8
|
+
|
|
9
|
+
A session token in a page — in `localStorage`, or in the script-readable cookie copy `browserEnv({ cookie: true })` kept — is there for anything else that runs in that page to take. Now the server writes the session into a cookie the page cannot read (`HttpOnly`, `SameSite=Lax`; `__Host-` prefixed and `Secure` over https) in its answer to the socket's upgrade, and the browser sends it by itself with the two requests that need to know who is asking: the page, and the upgrade. After a reload the page holds nothing.
|
|
10
|
+
|
|
11
|
+
**The setup this stops working for:** code that read the session token out of the page. `localStorage['nisc.token']` is empty once the browser holds the session, and the cookie copy is no longer written, so anything that took the token from there — to call a route with `Authorization: Bearer`, say — finds nothing. No route answers to the new cookie, on purpose: a browser sends a cookie with requests another site makes it send. And `renderDocument` no longer answers a cookie that does not resolve with a `Set-Cookie` that takes it back; the upgrade is the one place the cookie is written.
|
|
12
|
+
|
|
13
|
+
What happens, and to whom:
|
|
14
|
+
- **Only the app's own page.** The cookie is read and written when the upgrade's `Origin` is the host it was addressed to, or one listed in the new `runtime.origins` (for a proxy that rewrites `Host`). A page on another origin — which a browser sends the cookie with all the same — is nobody. A terminal that is not a page of its app (a process on `nodeEnv`, a page served from somewhere else, a browser that refuses cookies) holds its own token and offers it, exactly as before.
|
|
15
|
+
- **Nobody is signed out by the update.** A token an earlier build left in storage is offered once, moved into the cookie by the answer, and removed from storage along with the old copy.
|
|
16
|
+
- **Seats.** The cookie is named by the terminal's `tokenKey`, so several people can be signed in on one origin as before; the terminal names its key in the socket's address (`?key=`), and `renderDocument`'s `tokenKey` reads the same one. The name ends with the port when the page is on one — a browser keeps cookies by host, not port, and two apps on localhost would otherwise sign each other out — so `renderDocument` takes `request.host`; `mountSite` and the vite plugin pass it.
|
|
17
|
+
- **Signing out.** A cookie that no longer resolves is taken back on the next upgrade. Under an app's own identity provider the token may go on resolving, so a terminal that was signed out says so (`?leave=1`) and the cookie is taken back whatever it holds.
|
|
18
|
+
- **A sign-in the app answers over HTTP** (a link redeemed, a provider's callback) sets the cookie itself: `sessionCookies(request, token, { key?, lastsMs? })`, exported from the package root, returns the `Set-Cookie` values. The page that follows is signed in and was never handed the token. The vite plugin's `/dev/as/<who>` does this now.
|
|
19
|
+
- **A transport of your own** passes what the request carried — `connection.upgrade = { offered, origin, host, cookie }` — and, to let the cookie be written, leaves the request unanswered until the connection is first used, answering then with the cookies moss named through `upgrade.answer(cookies)` (moss names them before it uses the connection, and names none when there are none to write). One that has already answered reads the cookie and writes none. `attachSocket` does both.
|
|
20
|
+
- **A `WireEnv` of your own** is unchanged: without `tokens.held` a terminal stores its token as it always did.
|
|
21
|
+
|
|
22
|
+
**What to change:** nothing in an app that uses `createWire` with `browserEnv()` and serves with `serve`, `nisc start`, the vite plugin or `attachSocket`. `browserEnv({ cookie: true })` still compiles and the option now does nothing; drop it when convenient. A sign-in page that writes the token to `localStorage` keeps working (the token is moved on the next upgrade), and is better replaced by `sessionCookies` on the response. Behind a proxy that rewrites `Host`, list the app's origin in `runtime.origins` — until then every page looks like one served from somewhere else, so the app works as it did before this change, each terminal holding its own token, and moss says so once in the log. An app that draws its own pages passes `request.host` to `renderDocument`; behind a proxy that rewrites `Host` to an upstream on another port, `site` is where the port is taken from.
|
|
23
|
+
|
|
24
|
+
- 51dc5ce: DESIGN says what a rebuilt shell holds. "Durability" named a projection as the durable thing, and moss has built none ("Deliberately unbuilt" lists it). It now says the database is the durable thing: a shell is rebuilt on the next connection from definitions and whatever the app reads from rows as it builds, and evicting an idle shell, restarting the process and `reset` each cost what was only in the shell — the screens someone had opened, and what they had typed. Two source comments now say the same. No code changed.
|
|
25
|
+
|
|
26
|
+
**What to change:** nothing.
|
|
27
|
+
|
|
28
|
+
- da42472: With `shellFrameDelta` on, a canvas whose frame is over 64 KB is sent whole, and no longer compared.
|
|
29
|
+
|
|
30
|
+
Encoding a delta costs the server in proportion to the size of the two frames, not of the change, and it does the work on the thread every session shares. Nothing bounded it. Measured on the encoder alone: a 0.3 MB frame held the thread 65 ms for one changed letter, a 2.7 MB frame over a second, and at 20 MB it ran for eight seconds, took a gigabyte and failed — after which the frame was sent whole anyway. Every session on the process waited each time. A large frame needs nothing unusual: a long table, or one long value in a bound field, which any terminal can send. Now a change is sent whole, with no encode, when the frame the terminals hold or the frame replacing it is longer than 64 KB — where an in-place change measured about 7 ms.
|
|
31
|
+
|
|
32
|
+
Nothing moves with `shellFrameDelta` off (the default), for a terminal that did not ask for deltas, or on a canvas whose frames are at most 64 KB: those are byte for byte what they were. The rendered tree is the same in every case.
|
|
33
|
+
|
|
34
|
+
**What to change:** nothing. With deltas on, a change to a canvas over 64 KB now costs that canvas's whole frame on the wire — what a terminal that never asked for deltas is sent — where it had cost a delta, after the encode.
|
|
35
|
+
|
|
36
|
+
- a91b5db: `migrateTables`: the step that changes the tables, and checks the app's entries against what it leaves before it commits. `runtime.tables` hands it the app's own.
|
|
37
|
+
|
|
38
|
+
A deployment whose runtime says `migrations: 'verify'` refuses to start with anything pending, and moss had nothing to run first. An app's own tables were outside that run, so `'verify'` did not cover them.
|
|
39
|
+
|
|
40
|
+
`runtime.tables` takes the app's own table sequences (and another owner's the app keeps — tide's `TIDE_SEQUENCE`). They join moss's one ledgered run, after moss's own. A runtime that hands tables over does not also migrate them itself.
|
|
41
|
+
|
|
42
|
+
`migrateTables(runtime, app, { dryRun? })` applies everything pending in that run and, before it may commit, checks every entry of the manifest against the schema as it would stand: a read is resolved, a write is put to the gates it passes before it runs (vex's `mutationMisfits`). An entry that does not fit refuses the run — strata's `DOES_NOT_FIT`, each reason as `fingerprint: why` — and nothing is applied. It checks when nothing was pending too, so a release that changes an entry and no table is checked.
|
|
43
|
+
|
|
44
|
+
One kind of entry is listed and not refused: one that already did not fit before the run and that the database already holds seeded exactly as it is. A new or changed entry gets no such pass. The report also says which tables and columns a run removed and which column types it changed.
|
|
45
|
+
|
|
46
|
+
It sees entries and nothing else: not SQL written by hand, not a column a scope rule stamps, not what a value means.
|
|
47
|
+
|
|
48
|
+
**What to change:** nothing. A boot applies and verifies exactly what it did: a runtime without `tables` runs the same sequences in the same order.
|
|
49
|
+
|
|
50
|
+
- 812c464: `runtime.vexConfig` hands the query engine its settings.
|
|
51
|
+
|
|
52
|
+
Moss built the vex engine with no `config`, so a deployment ran on vex's defaults — 100 rows for a list that states no limit, 1000 at most, a ten-second read timeout — and had no way to change one.
|
|
53
|
+
|
|
54
|
+
`NiscRuntime` takes an optional `vexConfig`, passed to `createQueryEngine` as its `config` unread: `defaultLimit`, `maxLimit`, `capAuthored`, `statementTimeoutMs` and the rest of `QueryEngineConfig['config']`. Unset, the engine is built exactly as before.
|
|
55
|
+
|
|
56
|
+
**What to change:** nothing. Set `vexConfig` in your runtime to change one of the engine's numbers — for example `vexConfig: { capAuthored: true }` to keep seeded entries under `maxLimit`.
|
|
57
|
+
|
|
58
|
+
- 770f754: A frame the websocket transport refuses closes that connection; it no longer ends the process.
|
|
59
|
+
|
|
60
|
+
`attachSocket` listened for a connection's messages and its close, and not for its errors. `ws` reports what it refuses from a client — a malformed frame, text that is not UTF-8, a message over its size limit — as an `error` on that connection, and Node throws an `error` nobody listens for. So one such frame, from any client that could open the socket, signed in or not, ended the server process and every session on it. The transport now listens: `ws` has already closed the connection with the status that says why (1002, 1007, 1009), one line is logged (`[moss/node] a connection was closed on what it sent: …`), and nothing else is touched. Every host that calls `attachSocket` gets it — `serve`, `nisc start`, the vite plugin, an app's own listener.
|
|
61
|
+
|
|
62
|
+
**What to change:** nothing. An app this had happened to was not running. A process-level `uncaughtException` handler that was catching these no longer hears them.
|
|
63
|
+
|
|
64
|
+
- 61a4060: A sign-in made over the socket no longer hands the page its token. It reaches the page sealed, and only that browser can open it.
|
|
65
|
+
|
|
66
|
+
`session.grant(token)` happens on a socket, and a socket cannot write a cookie — so the token has to travel through the page to the terminal's next upgrade, where the session cookie is written. It used to travel as itself, which for that moment put it where any script in the page could take it. Now it travels encrypted with a key the browser holds in a second cookie no script can read (the _seal_), given by the answer to the browser's first upgrade. The page hands the sealed sign-in back and cannot open it; neither can anybody it is shown to, on this machine or another — without that browser's seal it opens nothing, and after a minute it opens nothing at all.
|
|
67
|
+
|
|
68
|
+
**The setup this stops working for:** none that worked. What is new for a browser: a terminal on `browserEnv()` now names `sealed=1` in the socket's address, and a browser that opens a socket to its app is given one more cookie — `nisc.seal` (`__Http-nisc.seal` over https): `HttpOnly`, `SameSite=Lax`, sent with the socket's path and no other, kept until the browser closes. It is given whether or not anybody signs in. It is a key, not a name: it is not stored or looked up on the server, and no page request carries it, so a page drawn for nobody stays cacheable for everybody.
|
|
69
|
+
- **Any credential, any number of processes.** Nothing is kept on the server between the sign-in and the upgrade that completes it, so it does not matter which process answers either, and the token can be moss's own or an app's provider's.
|
|
70
|
+
- **Terminals that keep their own token are handed it as before:** a process on `nodeEnv`, a page served from another origin, a `WireEnv` without `tokens.held`, a transport that cannot answer an upgrade late. `{ type: 'session', token }` is unchanged for them.
|
|
71
|
+
- **A browser that does not keep the seal** — it sends none back with the sealed sign-in — is told (`seal_not_kept`); its terminal stops asking, and the next sign-in reaches it as a token. That costs such a browser one failed sign-in.
|
|
72
|
+
- **A terminal written by hand** that wants sealed sign-ins: `?sealed=1` on the address from the app's own origin; a `{ type: 'session', sealed }` message is offered back with `offerToken(null, sealed)`.
|
|
73
|
+
|
|
74
|
+
The seal's name over https is what keeps a script from supplying it: the seal is given after the page's script has started, and a script already running then could otherwise set one of its own first and open the sign-in that follows. `__Http-` is a name a browser lets only an HTTP answer set. Not closed: a browser that does not know that prefix treats it as any other name; and a server on a sibling subdomain can still set one, which with a script in the page as well is the same opening.
|
|
75
|
+
|
|
76
|
+
**What to change:** nothing.
|
|
77
|
+
|
|
78
|
+
- 8012cd8: A message a terminal sends over the socket is at most 256 KB; a host that takes larger ones says so with `attachSocket`'s new `maxMessageBytes`.
|
|
79
|
+
|
|
80
|
+
**The setup this stops working for:** an app whose terminal sends a message over 256 KB — in practice a file put into a model value as base64 (a picked picture is megabytes). That message now closes the connection with `1009` and what it carried does not arrive; the terminal reconnects as after any other close, and a signed-in person's shell is as it was. To keep the old behaviour, a host that calls `attachSocket` passes the size it takes: `attachSocket(httpServer, server.socket, '/socket', { maxMessageBytes: 100 * 1024 * 1024 })` is what `ws` did before. `serve()`, `nisc start` and the vite plugin take the default and cannot raise it; an app on one of those that needs more attaches the socket itself. Better than raising it, and what `AGENTS.md` rule 9a says: a file never goes over the socket — the picker sends it to a route the app mounts, and the event carries what the route answered.
|
|
81
|
+
|
|
82
|
+
Why there is a limit. `attachSocket` created its `WebSocketServer` with no `maxPayload`, so the limit was `ws`'s own 100 MiB. Whatever a message carries, the server keeps — the value in the shell, and again in the last frame it sent — and sends back down in every later frame of that canvas. So the limit is what one connection, signed in or not, can make the process hold and re-send. Measured per open connection: 0.2 MB with nothing sent, 1.5 MB after a 256 KB value, 3.3 MB after 1 MiB, 48 MB after 16 MiB. Compression does not bound it — a 64 MB message of one repeated letter is 60 KB on the wire — so the count is of the message once inflated. What a terminal legitimately sends is an event: a press, a typed value, a row handed back. A few KB.
|
|
83
|
+
|
|
84
|
+
**What to change:** nothing, unless a terminal of yours sends more than 256 KB in one message — then one of the two things above. A typed value still has about 250,000 characters of room.
|
|
85
|
+
|
|
86
|
+
- 10875eb: A terminal's session token no longer rides the socket's address. It is offered in a header of the same request, and a token in the address is not read.
|
|
87
|
+
|
|
88
|
+
**The setup this stops working for:** a terminal and a server that are not the same version. The wire protocol is now 2 and the server speaks nothing older, so a terminal built before this is refused with `client_too_old` and a `4426` close — the existing "reload to get the current build" path — and a terminal built after it is refused by an older server with `server_too_old`. An app's terminal and server are one package and deploy together, so in practice this is a tab left open across the deploy: it reloads once. Three things written by hand also change:
|
|
89
|
+
- **A terminal written by hand** (`new WebSocket(`…/socket?token=…`)`, as a check or a script does) names the protocol and offers the token: `new WebSocket(`${base}/socket?protocol=${PROTOCOL}`, offerToken(token))`. `PROTOCOL` and `offerToken` are exported from `@niscorp/moss`; `offerToken(null)` is a terminal that is nobody.
|
|
90
|
+
- **A `WireEnv` of your own**: `socket` takes `{ url, offered }` where it took `url`, and constructs `new WebSocket(url, offered)`. One argument on purpose — an env that kept the old shape would have gone on compiling and connected everybody as nobody; this way it does not compile.
|
|
91
|
+
- **A transport of your own** (anything that is not `attachSocket`) hands over what the request offered: `connection.upgrade = { offered }`, the `Sec-WebSocket-Protocol` header split on commas, and answers the subprotocol `nisc`. Without it every terminal is served as nobody.
|
|
92
|
+
|
|
93
|
+
Why. The token rode the upgrade's query string, and an address is what every proxy, load balancer and access log between a browser and the app writes down. The request has one header every host lets a terminal set, a browser included: the subprotocols it offers. So the terminal offers `nisc`, and beside it its token, base64url (a subprotocol is an HTTP token; a session token need not be); the server answers `nisc` and never the other. Who a terminal is is still decided on the upgrade request, before anything is served, so there is no connection that is open and waiting to be told. A server that kept reading `?token=` for older terminals would have kept the address open for as long as anything used it, which is why protocol 1 is refused rather than served.
|
|
94
|
+
|
|
95
|
+
**What to change:** nothing in an app that uses `createWire` with `browserEnv()` or `nodeEnv()` and serves with `serve`, `nisc start`, the vite plugin or `attachSocket`. Otherwise one of the three above. Anything that read `?token=` off the socket's address — a proxy rule, a check — no longer finds it there.
|
|
96
|
+
|
|
97
|
+
- fc50d20: `AGENTS.md` says where files go. Rule 9a: file pickers live in the kit; a file never goes over the socket; the app saves it wherever it wants. The review pass's "no `fetch` outside the endpoint layer" gains its one exception, to send a file. No code changed.
|
|
98
|
+
|
|
99
|
+
A picker that puts a file in its model value sends it over the socket as base64, and the tree brings it back on every render of that canvas. Measured against a moss server: one 15 MB file was 20 MB up and 100 MB down across five renders. Sent by the picker to a route the app mounts on its server, or to a system the app already has, the same file put nothing on the socket.
|
|
100
|
+
|
|
101
|
+
moss gains a test and nothing else: a route an app adds to the built server reads who is asking, as moss's own surfaces do.
|
|
102
|
+
|
|
103
|
+
**What to change:** nothing for the rule itself. But this release also limits a message a terminal sends to 256 KB (the moss entry on the socket's message limit), so a picker that emits a file's bytes as its model value now works only for a file under about 190 KB: send the file from the picker, as rule 9a says, or raise the limit where the app attaches the socket.
|
|
104
|
+
|
|
3
105
|
## 0.3.2
|
|
4
106
|
|
|
5
107
|
### Patch Changes
|
package/DESIGN.md
CHANGED
|
@@ -135,9 +135,12 @@ compiles it.
|
|
|
135
135
|
## The socket
|
|
136
136
|
|
|
137
137
|
The authority channel. Transport-blind: the protocol speaks through a
|
|
138
|
-
four-function `Connection` seam (`send`/`close`/`onMessage`/`onClose
|
|
139
|
-
RFC 6455 plumbing lives with each
|
|
140
|
-
Bun-native later).
|
|
138
|
+
four-function `Connection` seam (`send`/`close`/`onMessage`/`onClose`, and what
|
|
139
|
+
the upgrade request offered), and the RFC 6455 plumbing lives with each
|
|
140
|
+
runtime's entry (`ws` on Node in `./node`, Bun-native later). Who a terminal is
|
|
141
|
+
is decided on that request, from its headers — a session cookie its browser
|
|
142
|
+
sent, or a token it offers as a subprotocol beside `nisc` — and never from its
|
|
143
|
+
address, which every proxy on the way logs. One connection per client carries every canvas — ten open
|
|
141
144
|
canvases are ten canvas ids on one pipe.
|
|
142
145
|
|
|
143
146
|
**Down:** `hello` (the resolved catalog on connect, and the protocol the server speaks — the terminal names its own on the upgrade), `catalog` (declared for
|
|
@@ -163,11 +166,12 @@ Operational shape, all falling out of "the message is state, not history":
|
|
|
163
166
|
same rule holds before the first connect: nothing is sent on a socket that is
|
|
164
167
|
not open and nothing is held for when it is. A server-drawn page (below) is on
|
|
165
168
|
screen before its socket, so a press in that moment is dropped.
|
|
166
|
-
- **Durability.** The
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
169
|
+
- **Durability.** The database is the durable thing; a shell is a warm cache,
|
|
170
|
+
rebuilt on the next connection from definitions and whatever the app reads
|
|
171
|
+
from rows as it builds. Evicting an idle shell, restarting the process and
|
|
172
|
+
`reset` cost the same and nothing more: what was only in the shell — the
|
|
173
|
+
screens someone had opened, and what they had typed. This is why an idle
|
|
174
|
+
sweep can exist at all.
|
|
171
175
|
- **Recovery.** `reset` (up) throws a session's shell away and serves its
|
|
172
176
|
replacement. It names no canvas, because it is the recovery for a session
|
|
173
177
|
whose canvases are the broken thing; it is protocol-level, so no action
|
|
@@ -192,6 +196,58 @@ Operational shape, all falling out of "the message is state, not history":
|
|
|
192
196
|
- **Size.** Two optional reductions — transport compression and frame deltas —
|
|
193
197
|
sit under the protocol, both off the app's books. See below.
|
|
194
198
|
|
|
199
|
+
### Where a browser keeps its session
|
|
200
|
+
|
|
201
|
+
A terminal served by the app it talks to does not hold its session. Its browser
|
|
202
|
+
does, in a cookie no script can read, and sends it by itself with the two
|
|
203
|
+
requests that need to know who is asking: the page, and the upgrade that opens
|
|
204
|
+
the socket. A token in the page — in storage, in a cookie script can read — is
|
|
205
|
+
there for anything else that runs in the page to take; one the page never has
|
|
206
|
+
cannot be taken from it.
|
|
207
|
+
|
|
208
|
+
- **The answer to the upgrade is where the cookie is written.** A cookie is set
|
|
209
|
+
by an HTTP response and by nothing else, and the upgrade is the one request
|
|
210
|
+
every terminal already makes. So who is asking is decided *before* the
|
|
211
|
+
request is answered, and the answer carries the cookie.
|
|
212
|
+
- **A sign-in over the socket reaches it sealed.** `session.grant` happens on a
|
|
213
|
+
socket, which cannot write a cookie; the token has to travel through the
|
|
214
|
+
page to the next upgrade. It travels encrypted with a key the browser holds
|
|
215
|
+
in a second cookie no script can read or set — the *seal*, given by the
|
|
216
|
+
answer to the browser's first upgrade under a name (`__Http-`) a browser
|
|
217
|
+
lets only an HTTP answer set. The page can hand a sealed sign-in back and
|
|
218
|
+
cannot open it, and neither can anybody it is shown to: without that
|
|
219
|
+
browser's seal it opens nothing. Nothing is kept here between the two
|
|
220
|
+
requests, so it works whichever process answers the second, and it works
|
|
221
|
+
for any credential — moss's own, or an app's provider's. The seal rides only
|
|
222
|
+
the socket's path, so no page request carries it and a page drawn for nobody
|
|
223
|
+
is still the same for everybody.
|
|
224
|
+
- **Only for the app's own page.** A browser sends a cookie with any page's
|
|
225
|
+
request to this host, a stranger's included, and the socket is the whole
|
|
226
|
+
app. So the cookies are read and written only when the request's `Origin` is
|
|
227
|
+
the host it was addressed to (or one `runtime.origins` lists, behind a proxy
|
|
228
|
+
that rewrites `Host`). From anywhere else a terminal is who the token it
|
|
229
|
+
offers says, or nobody.
|
|
230
|
+
- **No route answers to it.** The HTTP surfaces read `Authorization` and
|
|
231
|
+
nothing else, so no request another site can make a browser send does
|
|
232
|
+
anything as the person. A page request does read it — every site may link to
|
|
233
|
+
a page, and none can read the answer.
|
|
234
|
+
- **Its name is the terminal's token key**, so several people can be signed in
|
|
235
|
+
on one origin, each in a seat. It ends with the port when the page is on
|
|
236
|
+
one: a browser keeps cookies by host, not by port, and two apps on localhost
|
|
237
|
+
would sign each other out. Over https it is `__Host-` prefixed and `Secure`,
|
|
238
|
+
which a browser lets nothing but this host set.
|
|
239
|
+
- **What the page sees is a flag** (`<name>.held=1`), with no secret in it: how
|
|
240
|
+
a terminal knows to let go of a token it was holding, and that a page drawn
|
|
241
|
+
for somebody was drawn for it.
|
|
242
|
+
- **Signing out says so.** moss revokes its own credential, and a cookie that
|
|
243
|
+
no longer resolves is taken back on the next upgrade. An app's own provider's
|
|
244
|
+
token may go on resolving, so a terminal that was signed out says it is
|
|
245
|
+
leaving, and the cookie is taken back whatever it holds.
|
|
246
|
+
- **Any other terminal holds its own token** — a process, a page served from
|
|
247
|
+
somewhere else, a browser that refuses cookies — offers it, and is handed a
|
|
248
|
+
sign-in as its token, as before. A token such a page of the app's own offers
|
|
249
|
+
(one an earlier build left in storage) is moved into the cookie and let go of.
|
|
250
|
+
|
|
195
251
|
### What a frame costs
|
|
196
252
|
|
|
197
253
|
A server-authored shell pays for its inversion in bytes: every change re-sends
|
|
@@ -236,7 +292,11 @@ Three rules keep it honest:
|
|
|
236
292
|
everyone — so one encode serves the whole room.
|
|
237
293
|
2. **Decisively smaller, or whole.** A delta is only sent at ≤60% of the frame.
|
|
238
294
|
Below that it wins even after deflate; above it, deflate on the whole frame
|
|
239
|
-
does as well and the terminal does less work.
|
|
295
|
+
does as well and the terminal does less work. And a frame over 64 KB is not
|
|
296
|
+
compared at all: the encode's cost follows the size of the frames, not of
|
|
297
|
+
the change, on the thread every session shares — about 7 ms at 64 KB, a
|
|
298
|
+
second at 2.7 MB — so past that length, on either side of the change, the
|
|
299
|
+
canvas is sent whole before anything is spent on finding out.
|
|
240
300
|
3. **Checksummed, always.** Every delta carries a hash of the frame it should
|
|
241
301
|
rebuild. A terminal that lands anywhere else discards the result and sends
|
|
242
302
|
`resync` — the failure this layer must not have is a screen that is silently
|
|
@@ -389,11 +449,11 @@ Six things had to be true, and each is a small, separate decision:
|
|
|
389
449
|
`initializing`" is the shell saying its first screen is complete — a signal
|
|
390
450
|
that was always there. The wait is bounded (300 ms by default): a document
|
|
391
451
|
must not hang on a slow integration, and a skeleton is a legitimate screen.
|
|
392
|
-
- **Who is asking comes off
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
452
|
+
- **Who is asking comes off the browser's session cookie**, because a page
|
|
453
|
+
request carries nothing else (*Where a browser keeps its session*). It is
|
|
454
|
+
read here and never written: the upgrade is where it is set and taken back,
|
|
455
|
+
and one writer cannot disagree with itself. A cross-site request that carried
|
|
456
|
+
it could draw a page it cannot read.
|
|
397
457
|
- **An anonymous page and its socket are two shells that must name their
|
|
398
458
|
instances alike.** A principal's page is drawn from their durable shell and
|
|
399
459
|
the socket attaches to that same shell — same ids, nothing to arrange. Nobody
|
|
@@ -599,11 +659,16 @@ On the record, so nothing reads as finished that isn't:
|
|
|
599
659
|
drawn for nobody (a file, on a static host) connects, and is served a page
|
|
600
660
|
shell for as long as it stays — even when that page turns out not to be live
|
|
601
661
|
for them either. Closing such a connection once its frames are sent is unbuilt.
|
|
602
|
-
- **A
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
662
|
+
- **A seal no script can supply, in every browser.** The seal is given by the
|
|
663
|
+
answer to a browser's first upgrade, after the page's script has started; a
|
|
664
|
+
script already running then could set one of its own first, and open the
|
|
665
|
+
sign-in that follows. Its `__Http-` name is what stops that — a browser lets
|
|
666
|
+
only an HTTP answer set it — and a browser that does not know the prefix
|
|
667
|
+
does not stop it. Nor does the name stop a *server* on a sibling subdomain
|
|
668
|
+
from setting one; with a script in the page as well, that is the same
|
|
669
|
+
opening. `__Host-Http-` would close it, and would put the seal on every page
|
|
670
|
+
request, ending the sharing of pages drawn for nobody. Over plain http there
|
|
671
|
+
is no such name, and nothing on the way is private either.
|
|
607
672
|
|
|
608
673
|
## Boundaries
|
|
609
674
|
|
package/DOCS.md
CHANGED
|
@@ -222,8 +222,10 @@ type NiscRuntime = {
|
|
|
222
222
|
pool: PgPool; // SQL
|
|
223
223
|
db: MutationClient; // writes
|
|
224
224
|
cache?: CacheBackend; // defaults to vex's postgres cache on `pool`
|
|
225
|
+
vexConfig?: QueryEngineConfig['config']; // the query engine's settings (limits, read timeout); default vex's own
|
|
225
226
|
session: SessionVerifier | 'sessions' | 'dev-open'; // REQUIRED — no default
|
|
226
227
|
migrations?: 'apply' | 'verify'; // the boot's ledgered run; default 'apply'
|
|
228
|
+
tables?: readonly Sequence[]; // the app's own table sequences, in that same run
|
|
227
229
|
shellIdleMs?: number; // idle shell eviction; default 30 min, `0` disables
|
|
228
230
|
endpointTimeoutMs?: number; // a server shell's endpoint call; default nova's, 30s
|
|
229
231
|
sessionRevalidateMs?: number; // live-socket re-verify; default 60s, `0` disables
|
|
@@ -271,6 +273,38 @@ refuses to boot if anything is, for a deployment that migrates as a deploy step.
|
|
|
271
273
|
`initIntegrations` and `initSessions` remain for hosts that are not moss's
|
|
272
274
|
server, and go through the same ledger.
|
|
273
275
|
|
|
276
|
+
`tables` on the runtime hands over the app's own table sequences. They join
|
|
277
|
+
that run after moss's — one transaction, one lock, one posture, so `'verify'`
|
|
278
|
+
covers them. Absent, the app migrates its own tables itself, as before. Another
|
|
279
|
+
owner's tables the app keeps go in the same list (`TIDE_SEQUENCE`), and a
|
|
280
|
+
runtime that hands tables over does not also migrate them itself.
|
|
281
|
+
|
|
282
|
+
#### `migrateTables(runtime, app, { dryRun? }): Promise<TablesReport>`
|
|
283
|
+
|
|
284
|
+
The step that changes tables, for a deployment that migrates before it starts
|
|
285
|
+
(`nisc migrate` calls it). It applies everything pending in the one run,
|
|
286
|
+
whatever `runtime.migrations` says, and before the run may commit it asks
|
|
287
|
+
whether `app`'s entries fit what it leaves: every read is resolved against the
|
|
288
|
+
schema as the transaction sees it, every write is put to the gate vex puts it
|
|
289
|
+
to before it runs (`mutationMisfits`: its table, the columns it writes, its
|
|
290
|
+
WHERE, its lookups, its conflict target, what it reads from an earlier
|
|
291
|
+
statement). An entry that does not fit refuses the run — strata's
|
|
292
|
+
`DOES_NOT_FIT`, each
|
|
293
|
+
reason as `fingerprint: why` — and nothing was applied. It asks on every run,
|
|
294
|
+
so a release that changes an entry and no table is checked too.
|
|
295
|
+
|
|
296
|
+
One kind of entry is said and not refused: one that already did not fit before
|
|
297
|
+
the run and that the database already holds seeded exactly as it is. That is an
|
|
298
|
+
old fault, not this run's. A new or changed entry gets no such pass.
|
|
299
|
+
|
|
300
|
+
`TablesReport` is strata's `{ applied, plan }` plus `removed` (tables and
|
|
301
|
+
columns the run takes away), `retyped` (columns whose type it changes, as
|
|
302
|
+
`table.column (was → now)`) and `alreadyBroken`. `dryRun` does all of it and
|
|
303
|
+
rolls it back.
|
|
304
|
+
|
|
305
|
+
It sees entries and nothing else: not SQL written by hand, not a column a scope
|
|
306
|
+
rule stamps, not what a value means.
|
|
307
|
+
|
|
274
308
|
**Documents are read in this code's grammars.** Stored integration actions
|
|
275
309
|
carry a `grammar` stamp (`INTEGRATION_ACTIONS_STORE`). At boot, after the
|
|
276
310
|
tables, moss upgrades every stored action that is behind — through nova's and
|
|
@@ -470,11 +504,15 @@ const page = await renderDocument({
|
|
|
470
504
|
```
|
|
471
505
|
|
|
472
506
|
- **Which shell**: the page `server.page(path)` names, else the app's.
|
|
473
|
-
- **For whom**: the principal behind the cookie
|
|
474
|
-
(`tokenKey`, default `nisc.token`), or nobody.
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
507
|
+
- **For whom**: the principal behind the browser's session cookie for the
|
|
508
|
+
wire's token key (`tokenKey`, default `nisc.token`), or nobody. The cookie's
|
|
509
|
+
name ends with the port a page is on, so `request.host` (the `Host` header)
|
|
510
|
+
is how a page on a port finds it; `mountSite` and the vite plugin pass it.
|
|
511
|
+
Behind a proxy that rewrites `Host` to its upstream, the port `site` names
|
|
512
|
+
is tried too.
|
|
513
|
+
A cookie that no longer resolves is nobody. Nothing is written here — the
|
|
514
|
+
upgrade is where the cookie is set and taken back. A verifier that *throws*
|
|
515
|
+
is a fault, not a sign-out: the page goes out undrawn.
|
|
478
516
|
- **`draw`** is a terminal that draws to a string — the app's kit bound to
|
|
479
517
|
`renderSnapshot` from `terminal/react/server`, `terminal/vue/server` or
|
|
480
518
|
`terminal/dom/server`. It may be async.
|
|
@@ -540,6 +578,28 @@ page. `embedSnapshot` writes the snapshot as a
|
|
|
540
578
|
(and U+2028/2029) escaped: a tree carries what people typed, and nothing in it
|
|
541
579
|
can close the element or open another.
|
|
542
580
|
|
|
581
|
+
#### `sessionCookies(page, token, options?)`
|
|
582
|
+
|
|
583
|
+
The `Set-Cookie` values that keep `token` in the browser of the page at this
|
|
584
|
+
origin — or, for `null`, take it back. For a sign-in the app answers over HTTP
|
|
585
|
+
(a link redeemed, a provider's callback): set them on the response, and the
|
|
586
|
+
page that follows is signed in having never held the token.
|
|
587
|
+
|
|
588
|
+
```typescript
|
|
589
|
+
server.get('/login', async (c) => {
|
|
590
|
+
const token = await mintSession(pool, principal, TTL_MS);
|
|
591
|
+
for (const cookie of sessionCookies(c.req.raw, token, { lastsMs: TTL_MS })) c.header('set-cookie', cookie, { append: true });
|
|
592
|
+
return c.redirect('/');
|
|
593
|
+
});
|
|
594
|
+
```
|
|
595
|
+
|
|
596
|
+
`page` is the request (its `Origin`, else where it was addressed and the
|
|
597
|
+
`X-Forwarded-Proto` it arrived with) or the page's origin as a string.
|
|
598
|
+
`options.key` is the seat (the terminal's `tokenKey`; default `nisc.token`);
|
|
599
|
+
`options.lastsMs` is how long the browser keeps it — left out, until the
|
|
600
|
+
browser closes. A sign-in made over the socket (`session.grant`) needs none of
|
|
601
|
+
this: the answer to the terminal's next upgrade writes the same cookie.
|
|
602
|
+
|
|
543
603
|
#### `createPageRouter(pages): PageRouter`
|
|
544
604
|
|
|
545
605
|
`{ match(path): { name, params } | undefined }` — the matching rule above, for a
|
|
@@ -777,6 +837,18 @@ measures the end.
|
|
|
777
837
|
- `Connection` — the transport seam: `{ send, close, onMessage, onClose }`.
|
|
778
838
|
- `ServerMessage` — `hello | catalog | frame | render | render-delta | session | error`.
|
|
779
839
|
- `ClientMessage` — `event | publish | resync | reset | back | popTo`.
|
|
840
|
+
- **A message a terminal sends is at most 256 KB**, counted as it is once
|
|
841
|
+
inflated. One over that closes the connection with `1009` — the transport's
|
|
842
|
+
own close, not one of moss's — and what it carried did not arrive: the
|
|
843
|
+
terminal reconnects as after any other close, and a signed-in person's shell
|
|
844
|
+
is as it was. The limit is the Node transport's (`attachSocket`'s
|
|
845
|
+
`maxMessageBytes`, below), and it is a bound on memory, not on speed: the
|
|
846
|
+
server keeps what a message carried — the value in the shell, and again in
|
|
847
|
+
the last frame it sent — and sends it back down in every later frame of that
|
|
848
|
+
canvas. An event is a press, a typed value, a row handed back. A file never
|
|
849
|
+
goes over the socket (AGENTS.md rule 9a): the picker sends it to a route the
|
|
850
|
+
app mounts, or to a system the app already has, and the event carries what
|
|
851
|
+
came back.
|
|
780
852
|
- `render-delta` is only ever sent to a connection that advertised `?delta=1`
|
|
781
853
|
on the upgrade, and only when the server is configured for it. Everything
|
|
782
854
|
else is served whole frames, unchanged. See [Wire size](#wire-size).
|
|
@@ -807,18 +879,59 @@ measures the end.
|
|
|
807
879
|
failing definitions, then the close. The refusal is that terminal's alone,
|
|
808
880
|
and reconnecting later is reasonable.
|
|
809
881
|
- `error` codes: `invalid_token`, `session_failed`, `client_too_old`,
|
|
810
|
-
`server_too_old`, `no_shell` (the app serves no shell), `invalid_message
|
|
882
|
+
`server_too_old`, `no_shell` (the app serves no shell), `invalid_message`,
|
|
883
|
+
`seal_not_kept` (a sealed sign-in came back with no seal to open it).
|
|
884
|
+
- **Who a terminal is** is decided on the upgrade request, from a header of
|
|
885
|
+
it — never from its address, which is what every proxy on the way writes
|
|
886
|
+
into its log. A terminal offers the subprotocol `nisc`, and beside it its
|
|
887
|
+
token when it holds one: `offerToken(token | null)` returns the list to
|
|
888
|
+
construct the socket with (`new WebSocket(url, offerToken(token))`), and the
|
|
889
|
+
server answers `nisc`. A token in the address (`?token=`) is not read. A
|
|
890
|
+
transport hands the offer over as `connection.upgrade.offered`
|
|
891
|
+
(`Sec-WebSocket-Protocol`, split); one that leaves it out serves every
|
|
892
|
+
terminal as nobody. `attachSocket` does it.
|
|
893
|
+
- **A browser on the app's own page** is who its session cookie says
|
|
894
|
+
([`sessionCookies`](#sessioncookiespage-token-options)). The cookie is read
|
|
895
|
+
only when the upgrade's `Origin` is the host it was addressed to, or one
|
|
896
|
+
`runtime.origins` lists. (Behind a proxy that rewrites `Host` and with
|
|
897
|
+
nothing listed, no page is the app's own: terminals hold their own tokens,
|
|
898
|
+
as before, and moss says so once in the log.) A token such a page offers is who it is and is
|
|
899
|
+
moved into the cookie by the answer to the upgrade; one that no longer
|
|
900
|
+
resolves is nobody (served, not refused) and is taken back. `?key=` names
|
|
901
|
+
which of the browser's sessions the terminal is — a seat; the cookie is named
|
|
902
|
+
by it. `?leave=1` is a terminal that was signed out: it is nobody whatever
|
|
903
|
+
its browser holds, and the cookie is taken back. A transport passes what the
|
|
904
|
+
request carried as `connection.upgrade` — `{ offered, origin, host, cookie }`
|
|
905
|
+
— and, when it has not answered the request yet, `answer(cookies)`: moss
|
|
906
|
+
calls it once who is asking is decided, with the `Set-Cookie` values to
|
|
907
|
+
answer with. A transport without `answer` reads cookies and writes none.
|
|
908
|
+
- **A sign-in is handed to such a page sealed.** A terminal whose browser can
|
|
909
|
+
keep a session says so (`?sealed=1`; `browserEnv` does), and the answer to
|
|
910
|
+
its first upgrade gives the browser a *seal*: a key in a second cookie no
|
|
911
|
+
script can read — or, over https, set (`__Http-nisc.seal`; `nisc.seal` over
|
|
912
|
+
plain http) — sent only with the socket's path. `session.grant(token)`
|
|
913
|
+
then reaches that terminal as `{ type: 'session', sealed }` — the token,
|
|
914
|
+
encrypted with the seal and good for a minute — which it offers back on its
|
|
915
|
+
next upgrade (`offerToken(null, sealed)`); the browser's seal opens it there
|
|
916
|
+
and the session cookie is written. Offered with another seal, altered, or
|
|
917
|
+
late, it opens nothing and the terminal is nobody. A browser that sent no
|
|
918
|
+
seal to open it with does not keep cookies: the terminal is told
|
|
919
|
+
(`seal_not_kept`), stops asking, and is handed the next sign-in as a token.
|
|
920
|
+
Any other terminal — a process, a page on another origin — is handed
|
|
921
|
+
`{ type: 'session', token }`, as before.
|
|
811
922
|
- **Protocol version.** `PROTOCOL` is the wire protocol this server speaks and
|
|
812
923
|
`PROTOCOL_MIN` the oldest it still serves. A terminal names its protocol on
|
|
813
|
-
the upgrade (`?protocol=N
|
|
814
|
-
|
|
815
|
-
|
|
816
|
-
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
|
|
820
|
-
|
|
821
|
-
and are
|
|
924
|
+
the upgrade (`?protocol=N`); one that names none speaks `1`, which is every
|
|
925
|
+
terminal built before the question existed. Outside the range the connection
|
|
926
|
+
is refused before anything is served: an `error` frame (`client_too_old` or
|
|
927
|
+
`server_too_old`) and a `4426` close. `hello` carries `protocol`, so a
|
|
928
|
+
terminal can refuse a server older than it can speak to. Bump `PROTOCOL` when
|
|
929
|
+
a message changes shape; raise `PROTOCOL_MIN` only when the server stops
|
|
930
|
+
speaking an old one. Both are `2` today: at `1` the token rode the address,
|
|
931
|
+
and a server that went on reading it there would keep that open. `PROTOCOL`
|
|
932
|
+
and `offerToken` are exported from the package root, for a terminal written
|
|
933
|
+
by hand; `PROTOCOL_MIN` and `CLOSE_PROTOCOL_MISMATCH` are defined in
|
|
934
|
+
`src/socket.ts` and are not.
|
|
822
935
|
- **`?path=`** — the path the terminal is on. A path that leads to a page is
|
|
823
936
|
served that page's shell, built for this connection alone and seeded with the
|
|
824
937
|
path's parameters; any other path (and no path) is the app's shell. A
|
|
@@ -878,6 +991,12 @@ at most 60% of the whole frame. A terminal that never advertises — including
|
|
|
878
991
|
every terminal built before this existed — receives whole frames forever, from
|
|
879
992
|
the same shell, in the same pass. The two kinds of connection coexist.
|
|
880
993
|
|
|
994
|
+
**A canvas whose frame is over 64 KB is always sent whole.** Comparing two
|
|
995
|
+
frames costs the server in proportion to their size, not to what changed, and
|
|
996
|
+
it does that work on the thread every session shares — about 7 ms at 64 KB, a
|
|
997
|
+
second at 2.7 MB. So when the frame a terminal holds, or the one replacing it,
|
|
998
|
+
is longer than 64 KB, the server does not compare them. It is not a setting.
|
|
999
|
+
|
|
881
1000
|
What it buys, measured on Lyra:
|
|
882
1001
|
|
|
883
1002
|
| change | delta, as a share of the whole frame |
|
|
@@ -906,10 +1025,19 @@ Correctness, which matters more than the saving:
|
|
|
906
1025
|
in one process. `port` defaults to 8787.
|
|
907
1026
|
- `attachSocket(httpServer, accept, path?, options?)` — embed the socket on an
|
|
908
1027
|
existing server (raw `ws`, `noServer`, path-matched — coexists with vite
|
|
909
|
-
HMR). `path` defaults to `/socket`. `options = { compression
|
|
910
|
-
|
|
911
|
-
|
|
912
|
-
|
|
1028
|
+
HMR). `path` defaults to `/socket`. `options = { compression?,
|
|
1029
|
+
maxMessageBytes? }`. `compression` is the same value as
|
|
1030
|
+
`runtime.socketCompression` and defaults to `true`; `serve()` passes the
|
|
1031
|
+
runtime's through for you, so only a host running its own listener (a vite
|
|
1032
|
+
plugin, a dev check) ever needs it. `maxMessageBytes` is the largest message
|
|
1033
|
+
a connection may send, in bytes, and defaults to 256 KB (`256 * 1024`); a
|
|
1034
|
+
message over it closes that connection with `1009`. It is handed to `ws` as
|
|
1035
|
+
`maxPayload`, whose own default was 100 MiB. Only a host that calls
|
|
1036
|
+
`attachSocket` itself can raise it: `serve()`, `nisc start` and the dev
|
|
1037
|
+
plugin take the default.
|
|
1038
|
+
- A frame the transport refuses — malformed, not UTF-8, over the limit — ends
|
|
1039
|
+
that connection (`1002`, `1007`, `1009`) and logs one line; no other
|
|
1040
|
+
connection is touched.
|
|
913
1041
|
|
|
914
1042
|
- `mountSite(server, { dist, draw, htmlAttributes?, site?, tokenKey?, waitMs?, owned? })`
|
|
915
1043
|
— the built terminal, served by the same process as the app. Every GET that
|
|
@@ -946,8 +1074,8 @@ Requires the optional `vite` peer.
|
|
|
946
1074
|
- `options.app(load): Promise<DevApp>` — stand the app up. `load` is vite's
|
|
947
1075
|
`ssrLoadModule`. `DevApp = { server, close?, draw?, htmlAttributes?,
|
|
948
1076
|
site?, tokenKey?, signIn? }`; absent `draw`, pages go out undrawn.
|
|
949
|
-
- `signIn(who)` enables `/dev/as/<who>`: it
|
|
950
|
-
|
|
1077
|
+
- `signIn(who)` enables `/dev/as/<who>`: it puts the returned token in the
|
|
1078
|
+
browser's session cookie and goes to `/`. `null` is nobody of that name.
|
|
951
1079
|
- `watch?: RegExp` (default: `src/app`, `src/server`, `src/db`, `src/ui` and
|
|
952
1080
|
the nisc config), `index?` (default `index.html`), `owned?` (default
|
|
953
1081
|
`MOSS_PATHS`), `label?` (default `moss`).
|
|
@@ -959,19 +1087,26 @@ Requires the optional `vite` peer.
|
|
|
959
1087
|
host-shaped comes in as a `WireEnv`. `delta` (default `false`) advertises
|
|
960
1088
|
that this terminal can rebuild frame deltas; the snapshot it produces is
|
|
961
1089
|
identical either way. See [Wire size](#wire-size).
|
|
962
|
-
- `WireEnv` — the host seam: `{ tokens: { load, save, clear },
|
|
963
|
-
defaultUrl() }`. The socket API is WHATWG-standard
|
|
964
|
-
Node ≥22, Bun); an env only constructs it
|
|
965
|
-
|
|
966
|
-
|
|
967
|
-
|
|
968
|
-
the
|
|
969
|
-
|
|
970
|
-
|
|
971
|
-
|
|
972
|
-
|
|
973
|
-
|
|
974
|
-
|
|
1090
|
+
- `WireEnv` — the host seam: `{ tokens: { load, save, clear, held?, key? },
|
|
1091
|
+
socket({ url, offered }), defaultUrl() }`. The socket API is WHATWG-standard
|
|
1092
|
+
in every host (browser, Node ≥22, Bun); an env only constructs it —
|
|
1093
|
+
`new WebSocket(url, offered)`. What is offered is who the terminal is, so an
|
|
1094
|
+
env that drops it connects as nobody. `held()` is for a host whose browser
|
|
1095
|
+
may keep the session itself: asked after an upgrade is answered, `true`
|
|
1096
|
+
makes the wire let go of the token it offered, `false` makes it store it. A
|
|
1097
|
+
host with `held` also asks to be handed sign-ins sealed. A host without it
|
|
1098
|
+
stores a token as soon as it is handed one. `key` names the terminal's seat
|
|
1099
|
+
in the socket's address.
|
|
1100
|
+
- `browserEnv({ tokenKey?, cookie? }?): WireEnv` — the default host: url
|
|
1101
|
+
derived from `window.location`, the page's WebSocket, and the session
|
|
1102
|
+
wherever the page can have it kept. Served by the app it talks to, the page
|
|
1103
|
+
does not keep it: the browser does, in a cookie the page cannot read, and
|
|
1104
|
+
`held` reads the flag beside it. Anywhere else — another origin, a browser
|
|
1105
|
+
that refuses cookies — the token is in localStorage under `tokenKey`
|
|
1106
|
+
(default `nisc.token`). `tokenKey` is also the seat, and the cookie's name.
|
|
1107
|
+
`cookie` is accepted and does nothing: it kept a script-readable copy of the
|
|
1108
|
+
token for the server to draw the page from, and the page is now drawn from
|
|
1109
|
+
the browser's own cookie.
|
|
975
1110
|
- `readDocumentSnapshot(doc?): DocumentSnapshot | undefined` — the snapshot a
|
|
976
1111
|
server-drawn page carries (`{ frame, trees, principal, seed?, path?, live? }`),
|
|
977
1112
|
or `undefined` for a page that carries none. Never throws. `principal` is a
|
|
@@ -1029,7 +1164,7 @@ outage ago.
|
|
|
1029
1164
|
|
|
1030
1165
|
```typescript
|
|
1031
1166
|
import { createWire } from '@niscorp/moss/client';
|
|
1032
|
-
const wire = createWire(); // browser host;
|
|
1167
|
+
const wire = createWire(); // browser host; the session is the browser's to keep
|
|
1033
1168
|
wire.subscribe(() => render(wire.snapshot()));
|
|
1034
1169
|
wire.dispatch('main', { type: 'ui:click', ref: 'save' });
|
|
1035
1170
|
```
|
package/README.md
CHANGED
|
@@ -83,7 +83,7 @@ server.get('*', async (c) => {
|
|
|
83
83
|
```typescript
|
|
84
84
|
// the browser's entry
|
|
85
85
|
const drawn = readDocumentSnapshot();
|
|
86
|
-
createWire({ env: browserEnv(
|
|
86
|
+
createWire({ env: browserEnv(), ...(drawn ? { initial: drawn } : {}) });
|
|
87
87
|
```
|
|
88
88
|
|
|
89
89
|
Who may keep the page follows from who asked: drawn for nobody it is the same
|
|
@@ -158,7 +158,7 @@ never in moss core.
|
|
|
158
158
|
|
|
159
159
|
- **`/catalog`** — the application, resolved for you (granted action ids + a version token).
|
|
160
160
|
- **`/api/vex`, `/api/<resource>/vex`** — reads and writes, locked (replay-only), scoped per principal. The model never writes SQL; the policy it can't see enforces access.
|
|
161
|
-
- **the socket** — the authority channel: the served frame and per-canvas `RenderNode` trees down, `NovaEvent`s up. Session lifecycle (sign-in grant, sign-out revoke) rides it. Two optional reductions sit under it, both invisible to an app: `permessage-deflate` (on by default) and frame deltas (`shellFrameDelta`, off) — a changed canvas sent as a checksummed delta against the frame the terminal already holds, 1–4% of the frame on an in-place change. See [DOCS.md § Wire size](DOCS.md#wire-size).
|
|
161
|
+
- **the socket** — the authority channel: the served frame and per-canvas `RenderNode` trees down, `NovaEvent`s up (a message a terminal sends is at most 256 KB). Session lifecycle (sign-in grant, sign-out revoke) rides it. Two optional reductions sit under it, both invisible to an app: `permessage-deflate` (on by default) and frame deltas (`shellFrameDelta`, off) — a changed canvas sent as a checksummed delta against the frame the terminal already holds, 1–4% of the frame on an in-place change. See [DOCS.md § Wire size](DOCS.md#wire-size).
|
|
162
162
|
|
|
163
163
|
## Tables and documents, versioned
|
|
164
164
|
|