foldkit-ssr 0.8.2 → 0.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +496 -83
- package/dist/client-XnpTQZHw.d.ts +85 -0
- package/dist/client-XnpTQZHw.d.ts.map +1 -0
- package/dist/client.d.ts +5 -0
- package/dist/client.js +343 -0
- package/dist/client.js.map +1 -0
- package/dist/context.d.ts +2 -0
- package/dist/context.js +33 -0
- package/dist/context.js.map +1 -0
- package/dist/diagnostics.d.ts +2 -0
- package/dist/diagnostics.js +59 -0
- package/dist/diagnostics.js.map +1 -0
- package/dist/{index.d.mts → index.d.ts} +96 -25
- package/dist/index.d.ts.map +1 -0
- package/dist/{index.mjs → index.js} +247 -108
- package/dist/index.js.map +1 -0
- package/dist/keep.d.ts +34 -0
- package/dist/keep.d.ts.map +1 -0
- package/dist/keep.js +80 -0
- package/dist/keep.js.map +1 -0
- package/dist/listen-DaUPRKVR.d.ts +71 -0
- package/dist/listen-DaUPRKVR.d.ts.map +1 -0
- package/dist/listen.d.ts +2 -0
- package/dist/listen.js +187 -0
- package/dist/listen.js.map +1 -0
- package/dist/requestContext-D9nsbGSJ.d.ts +21 -0
- package/dist/requestContext-D9nsbGSJ.d.ts.map +1 -0
- package/dist/requestContext.d.ts +2 -0
- package/dist/requestContext.js +48 -0
- package/dist/requestContext.js.map +1 -0
- package/dist/resumable-BPN_qQHU.d.ts +107 -0
- package/dist/resumable-BPN_qQHU.d.ts.map +1 -0
- package/dist/resumable.d.ts +2 -0
- package/dist/resumable.js +401 -0
- package/dist/resumable.js.map +1 -0
- package/dist/{client-DkwAniQQ.d.mts → shared-DbupL3vO.d.ts} +233 -194
- package/dist/shared-DbupL3vO.d.ts.map +1 -0
- package/dist/shared.d.ts +2 -0
- package/dist/shared.js +347 -0
- package/dist/shared.js.map +1 -0
- package/dist/{vite.d.mts → vite.d.ts} +3 -5
- package/dist/vite.d.ts.map +1 -0
- package/dist/{vite.mjs → vite.js} +3 -4
- package/dist/vite.js.map +1 -0
- package/package.json +18 -18
- package/dist/client-DVG9_3rL.mjs +0 -1113
- package/dist/client-DVG9_3rL.mjs.map +0 -1
- package/dist/client-DkwAniQQ.d.mts.map +0 -1
- package/dist/client.d.mts +0 -2
- package/dist/client.mjs +0 -1
- package/dist/index.d.mts.map +0 -1
- package/dist/index.mjs.map +0 -1
- package/dist/vite.d.mts.map +0 -1
- package/dist/vite.mjs.map +0 -1
package/README.md
CHANGED
|
@@ -13,6 +13,9 @@ pnpm add foldkit-ssr foldkit-surface foldkit effect
|
|
|
13
13
|
```
|
|
14
14
|
|
|
15
15
|
```ts
|
|
16
|
+
// In outline; `App`, `config` and `template` are the application's own, and
|
|
17
|
+
// [A first page](#a-first-page) splits this into its modules.
|
|
18
|
+
|
|
16
19
|
// Which part of the Model the browser owns.
|
|
17
20
|
const Post = SSR.plan(App, {
|
|
18
21
|
id: 'post',
|
|
@@ -59,12 +62,17 @@ It owns **the handover**: which slice crosses, how it is written into the page,
|
|
|
59
62
|
and the checks that the browser can start from it.
|
|
60
63
|
|
|
61
64
|
- **Rendering and adoption stay Foldkit's.** `SSR.render` calls Foldkit's
|
|
62
|
-
`renderToString` and `SSR.hydrate` calls `Runtime.hydrate
|
|
63
|
-
|
|
65
|
+
`renderToString` and `SSR.hydrate` calls `Runtime.hydrate`, which adopts the
|
|
66
|
+
server's nodes. `SSR.hydrate` compares the page's build id with its own
|
|
67
|
+
before it reads the envelope, so a Model serialized by another deployment is
|
|
68
|
+
never decoded.
|
|
64
69
|
- **The Model stays the application's.** A plan names fields of it; it adds no
|
|
65
70
|
state of its own, and every change after boot goes through `update`.
|
|
66
71
|
- **Data belongs to its package.** Remote's store crosses through Remote's own
|
|
67
72
|
part (`Remote.resume`), which decides what to capture.
|
|
73
|
+
- **What the browser stored stays the browser's.** The server cannot read a
|
|
74
|
+
queue kept in `localStorage`, so it is never in the page: it joins after
|
|
75
|
+
the first frame ([`prepare`](#what-only-the-browser-has-prepare)).
|
|
68
76
|
|
|
69
77
|
## The mental model
|
|
70
78
|
|
|
@@ -180,7 +188,8 @@ boot: model => assembly.init(model).commands ?? []
|
|
|
180
188
|
A generated page styled with `foldkit-mixins` can ship the CSS its markup uses
|
|
181
189
|
in the head, so it is styled before any script runs. `head` is given the rendered
|
|
182
190
|
application; `Style.usedIn` returns the CSS of every compiled class the markup
|
|
183
|
-
carries
|
|
191
|
+
carries, with the global rules (keyframes, `raise`'s depth rules) of the Styles
|
|
192
|
+
those classes came from. In the browser, Styles bring their rules as they draw and skip what
|
|
184
193
|
this sheet already carries, so nothing is added twice.
|
|
185
194
|
|
|
186
195
|
```ts
|
|
@@ -193,11 +202,27 @@ const html = SSR.page(template, result, {
|
|
|
193
202
|
|
|
194
203
|
A served page has no template head to write to, so `SSR.render`, `SSR.entry`
|
|
195
204
|
and `SSR.handle` take the same function as `styles` instead, carried as the
|
|
196
|
-
rendered root's last
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
205
|
+
rendered root's last children. `foldkit-mixins/foundations` writes the theme
|
|
206
|
+
into `index.html` only, never into a page the server renders, so a served
|
|
207
|
+
page carries the theme's stylesheet here too, beside the classes it draws
|
|
208
|
+
(`examples/foldkit/ssr/src/renderPage.ts`):
|
|
209
|
+
|
|
210
|
+
```ts
|
|
211
|
+
const styles = (rendered: { readonly html: string }): string =>
|
|
212
|
+
`<style>${stylesheet}</style><style>${Style.usedIn(rendered.html)}</style>`
|
|
213
|
+
|
|
214
|
+
SSR.entry(config, plan, { buildId, styles })
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
Without it, every served page flashes unstyled until the script runs. Keep
|
|
218
|
+
`styles` to `<style>` and stylesheet `<link>`s. The view does not draw them,
|
|
219
|
+
so hydration would remove them from the root, and a page that never renders
|
|
220
|
+
again would keep its classes without their rules; `SSR.hydrate` moves them
|
|
221
|
+
into the document's head before anything adopts the page, whether it resumes
|
|
222
|
+
or is contained, and the browser's Styles find them there and add nothing
|
|
223
|
+
twice. A void root holds no children, so styles for one are refused with
|
|
224
|
+
`VoidRootWithStyles`, naming the tag. Anything else a head owns (`meta`)
|
|
225
|
+
stays with `SSR.generate`.
|
|
201
226
|
|
|
202
227
|
`SSR.generate` takes the same `head`, and answers a `head` that throws `500`,
|
|
203
228
|
as it does a render that fails. `SSR.entry` takes no `head`: the host owns
|
|
@@ -271,6 +296,7 @@ export default {
|
|
|
271
296
|
```ts
|
|
272
297
|
// vite.config.ts, for the dev server and the build id both entries compile in.
|
|
273
298
|
import { foldkit } from '@foldkit/vite-plugin'
|
|
299
|
+
import { defineConfig } from 'vite'
|
|
274
300
|
|
|
275
301
|
export default defineConfig({
|
|
276
302
|
plugins: [foldkit({ ssr: { serverEntry: '/src/entry.server.ts' } })],
|
|
@@ -285,7 +311,22 @@ buildId: import.meta.env.FOLDKIT_BUILD_ID,
|
|
|
285
311
|
`FOLDKIT_BUILD_ID` names the deployment, from the environment: a commit or a
|
|
286
312
|
release tag, public and unique per deployment. The plugin compiles it into
|
|
287
313
|
both bundles; a script outside Vite, such as a prerender, reads
|
|
288
|
-
`process.env.FOLDKIT_BUILD_ID`, the same value the build saw.
|
|
314
|
+
`process.env.FOLDKIT_BUILD_ID`, the same value the build saw. With it unset,
|
|
315
|
+
`import.meta.env.FOLDKIT_BUILD_ID` is undefined in the client, and
|
|
316
|
+
`SSR.hydrate`, given no id, contains the page and reports why
|
|
317
|
+
([`PageContained`](#diagnostics), reason `NoBuildId`) rather than adopting it.
|
|
318
|
+
|
|
319
|
+
The client and the server must be built with one id. A page whose stamp is
|
|
320
|
+
not the client's is contained and reported as reason `OtherBuild`, naming both
|
|
321
|
+
ids. When nothing sets the variable and one `vite build` makes both bundles,
|
|
322
|
+
set it in `vite.config.ts` before `foldkit()` reads it, so every environment
|
|
323
|
+
of the build sees the same value (a script run after the build does not):
|
|
324
|
+
|
|
325
|
+
```ts
|
|
326
|
+
import { randomUUID } from 'node:crypto'
|
|
327
|
+
|
|
328
|
+
process.env.FOLDKIT_BUILD_ID ??= randomUUID()
|
|
329
|
+
```
|
|
289
330
|
|
|
290
331
|
Set it even though `@foldkit/vite-plugin` can now generate an id on its own.
|
|
291
332
|
The generated one is compiled into Foldkit alone, where `foldkit-ssr` cannot
|
|
@@ -294,25 +335,68 @@ so a Model serialized by another deployment is never decoded. Asking Foldkit
|
|
|
294
335
|
to expose that id is [proposal 4](../../docs/upstream-foldkit-ssr.md#proposal-4-expose-the-compiled-build-id).
|
|
295
336
|
|
|
296
337
|
`GET` and `HEAD` render the page for the request's URL; an application with
|
|
297
|
-
Flags passes `flags: request => ...`. `
|
|
338
|
+
Flags passes `flags: request => ...`. `prepare: (model, request) => Effect`
|
|
339
|
+
turns the Model `init` gave into the one the page is rendered from, for what
|
|
340
|
+
must be read before the render (`Data.satisfy`, [below](#what-the-host-hands-the-page-ssrrequestcontext))
|
|
341
|
+
or taken from the request (a cookie). It runs for a posted form too, before
|
|
342
|
+
the Message is checked against the active Surfaces and `update` runs, so the
|
|
343
|
+
post starts from the Model the page it came from was drawn with, and one
|
|
344
|
+
entry, made once, serves every request. A `prepare` that fails is answered
|
|
345
|
+
`500` and reported; one that would rather draw the page unread recovers
|
|
346
|
+
inside its Effect. `POST` is handled only for a plan with a
|
|
298
347
|
[server fallback](#forms-that-work-without-scripts). `OPTIONS` is answered
|
|
299
348
|
`204` and any other method `405`, each with the methods the entry answers in
|
|
300
349
|
`allow`. A render that fails or throws, `flags` that reject, and a plan the
|
|
301
|
-
render refuses are answered `500` with the reason
|
|
302
|
-
the browser could not resume.
|
|
350
|
+
render refuses are answered `500` with the reason reported
|
|
351
|
+
([`PageFailed`](#diagnostics)), never with a page the browser could not resume.
|
|
303
352
|
|
|
304
|
-
`headers: request => ...`
|
|
305
|
-
|
|
306
|
-
preflight, which reaches the entry and not the host
|
|
353
|
+
`headers: (request, model) => ...` is set over the host's own on every
|
|
354
|
+
answer: a cache policy for a page that is one visitor's, the CORS answer to a
|
|
355
|
+
preflight, which reaches the entry and not the host, or a cookie written from
|
|
356
|
+
the Model. `model` is an `Option`: `some` of the Model the server reached for
|
|
357
|
+
a rendered page (a posted form's, after `update`), `none` for an answer that
|
|
358
|
+
rendered nothing (`OPTIONS`, a `405`, a refused post, a `500`).
|
|
307
359
|
|
|
308
360
|
```ts
|
|
309
361
|
SSR.entry(config, Post, {
|
|
310
362
|
buildId,
|
|
311
|
-
headers: () => ({
|
|
363
|
+
headers: (_request, model) => ({
|
|
364
|
+
'cache-control': 'private, no-store',
|
|
365
|
+
vary: 'cookie',
|
|
366
|
+
...Option.match(model, {
|
|
367
|
+
onNone: () => ({}),
|
|
368
|
+
onSome: ({ post }) => ({
|
|
369
|
+
'set-cookie': `last-read=${encodeURIComponent(post.id)}; Path=/; SameSite=Lax`,
|
|
370
|
+
}),
|
|
371
|
+
}),
|
|
372
|
+
}),
|
|
312
373
|
})
|
|
313
374
|
```
|
|
314
375
|
|
|
315
|
-
A `headers` that throws is answered `500`, as a failed render is
|
|
376
|
+
A `headers` that throws is answered `500`, as a failed render is, and so is
|
|
377
|
+
one that sets what is not the application's to set: a name or value `Headers`
|
|
378
|
+
refuses (a value holding CR or LF cannot smuggle a second header in), a
|
|
379
|
+
header that frames the response (`content-length`, `transfer-encoding`,
|
|
380
|
+
`connection` and their kin), or `location`. A value from the Model still
|
|
381
|
+
needs encoding for its header, as `encodeURIComponent` does here: a cookie's
|
|
382
|
+
value holds no `;` or `,`.
|
|
383
|
+
|
|
384
|
+
Every rendered page is answered `200` unless `status: (model, request) =>
|
|
385
|
+
...` says otherwise. It is given the Model the server reached, which already
|
|
386
|
+
says which route it is, so a not-found page is answered `404` without parsing
|
|
387
|
+
the URL twice:
|
|
388
|
+
|
|
389
|
+
```ts
|
|
390
|
+
SSR.entry(config, Post, {
|
|
391
|
+
buildId,
|
|
392
|
+
status: model =>
|
|
393
|
+
AppRoute.match(model.route, { Home: () => 200, Post: () => 200, NotFound: () => 404 }),
|
|
394
|
+
})
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
The page is rendered and resumed as any other; only the response's status
|
|
398
|
+
changes. A status outside `200`–`599`, or a `status` that throws, is answered
|
|
399
|
+
`500` and reported.
|
|
316
400
|
|
|
317
401
|
What the page says of itself (`meta`) and per-page `head` markup are written
|
|
318
402
|
into a template's head, which the host owns here: a plan with `meta` is
|
|
@@ -321,6 +405,55 @@ owns its template.
|
|
|
321
405
|
[foldkit#1448](https://github.com/foldkit/foldkit/issues/1448) asks Foldkit
|
|
322
406
|
for a per-request head channel beside the envelope.
|
|
323
407
|
|
|
408
|
+
### What the host hands the page: `SSR.requestContext`
|
|
409
|
+
|
|
410
|
+
`handleRequest` calls `renderPage(request)` and nothing more, and the
|
|
411
|
+
`fetch(request)` a build emits passes on no Worker's `env`. A page that reads
|
|
412
|
+
before it renders (`Data.satisfy`) needs what only the host holds: the
|
|
413
|
+
bindings, or a reader built from them. `SSR.requestContext` carries it on the
|
|
414
|
+
request. The host attaches a value, and `renderPage`, given the same request
|
|
415
|
+
by `handleRequest`, reads it back:
|
|
416
|
+
|
|
417
|
+
```ts
|
|
418
|
+
import { Effect, Option, type Layer } from 'effect'
|
|
419
|
+
import type { RemoteClient, RemoteUnauthenticated } from 'foldkit-remote'
|
|
420
|
+
import { SSR } from 'foldkit-ssr'
|
|
421
|
+
|
|
422
|
+
// One module the host and the server entry both import.
|
|
423
|
+
export const PageContext = SSR.requestContext<{
|
|
424
|
+
readonly reader: Layer.Layer<RemoteClient, RemoteUnauthenticated>
|
|
425
|
+
}>('app/page')
|
|
426
|
+
|
|
427
|
+
// The host, a Worker's fetch say:
|
|
428
|
+
// pages.fetch(PageContext.attach(request, { reader: pageReader(page)(request, env) }))
|
|
429
|
+
|
|
430
|
+
// The server entry, made once. `actives` is the record `Data.wiring` takes.
|
|
431
|
+
export const { renderPage } = SSR.entry(config, Post, {
|
|
432
|
+
buildId,
|
|
433
|
+
prepare: (model, request) =>
|
|
434
|
+
Option.match(PageContext.of(request), {
|
|
435
|
+
onNone: () => Effect.fail(new Error('No reader for this page.')),
|
|
436
|
+
onSome: ({ reader }) => Data.satisfy(model, actives).pipe(Effect.provide(reader)),
|
|
437
|
+
}),
|
|
438
|
+
})
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
The value is kept for that request alone, in a `WeakMap` on `globalThis`
|
|
442
|
+
under a registered symbol, so a Worker's bundle and the page bundle Vite
|
|
443
|
+
built, each with its own copy of `foldkit-ssr`, find each other's values by
|
|
444
|
+
the context's name. Nothing outlives the request, and no request reads
|
|
445
|
+
another's. `of` is `Option.none()` for a request the host attached nothing
|
|
446
|
+
to: Vite's dev server builds its own `Request`, and a host that passes on a
|
|
447
|
+
copy (`new Request(request)`) drops it. A second value under one name on one
|
|
448
|
+
request throws. The value is not checked at run time: its type is the one the
|
|
449
|
+
shared module declares.
|
|
450
|
+
|
|
451
|
+
The reader is `pageReader` from `foldkit-remote-server/fetch`: the request's
|
|
452
|
+
Remote client, answered in the same process by the server `serveFetch`
|
|
453
|
+
serves. [`examples/auth`](../../examples/auth)'s `src/host.ts` is the whole
|
|
454
|
+
site behind one handler; its development server, another process, attaches
|
|
455
|
+
an HTTP reader instead.
|
|
456
|
+
|
|
324
457
|
### At build time
|
|
325
458
|
|
|
326
459
|
```ts
|
|
@@ -349,8 +482,36 @@ a tuple, so `const [home, about] = pages` needs no check.
|
|
|
349
482
|
|
|
350
483
|
A static host serves one file for every query, and for `/about` and `/about/`
|
|
351
484
|
alike, so a generated page records its path alone: `/about?ref=mail` resumes
|
|
352
|
-
the page generated for `/about`, and `/other` is refused.
|
|
353
|
-
|
|
485
|
+
the page generated for `/about`, and `/other` is refused. The page was made
|
|
486
|
+
without the query, and `init` does not run in the browser, so an application
|
|
487
|
+
with `routing` starts from the resumed Model given `routing.onUrlChange` of
|
|
488
|
+
the URL it is at, as from a navigation, and starts at once whatever its
|
|
489
|
+
`start`: one that reads the query (a search box in `?q=`) shows it, and the
|
|
490
|
+
part of the page that differs is redrawn; one that does not changes nothing.
|
|
491
|
+
The Message goes into the starting Model rather than after boot, so a URL
|
|
492
|
+
mirror does not write the served address back over the real one. A
|
|
493
|
+
server-rendered page records its path and query, and resumes only there.
|
|
494
|
+
|
|
495
|
+
Foldkit's Vite plugin prerenders pages through the server entry itself
|
|
496
|
+
(`ssr.build.prerender`), so `SSR.entry` cannot tell a build's request from a
|
|
497
|
+
visitor's. Name those paths in `prerendered`, and a request for one with no
|
|
498
|
+
query records its path alone, as `SSR.generate` does; export the same list
|
|
499
|
+
as `prerenderPaths`, which the plugin reads:
|
|
500
|
+
|
|
501
|
+
```ts
|
|
502
|
+
export const prerenderPaths = ['/']
|
|
503
|
+
|
|
504
|
+
export const { renderPage } = SSR.entry(config, Post, { buildId, prerendered: prerenderPaths })
|
|
505
|
+
```
|
|
506
|
+
|
|
507
|
+
A prerendered file the entry was not told of is refused at any other query,
|
|
508
|
+
and the reason says so.
|
|
509
|
+
|
|
510
|
+
Until the bundle runs, a file shows the state it was recorded with: the
|
|
511
|
+
query reaches the Model only when the browser starts. A page whose first
|
|
512
|
+
paint depends on its query (a search box filled from `?q=`) is better
|
|
513
|
+
rendered per request, which records the query and resumes with nothing
|
|
514
|
+
redrawn; `examples/foldkit/domains-plus` prerenders nothing for that reason.
|
|
354
515
|
|
|
355
516
|
A generated site also wants a sitemap and a `robots.txt` that names it.
|
|
356
517
|
`SSR.sitemap` takes the pages, with a `modified` date where one is known, and
|
|
@@ -382,7 +543,10 @@ application code:
|
|
|
382
543
|
|
|
383
544
|
```ts
|
|
384
545
|
// vite.config.ts
|
|
546
|
+
import { foldkit } from '@foldkit/vite-plugin'
|
|
385
547
|
import { staticSite } from 'foldkit-ssr/vite'
|
|
548
|
+
import { defineConfig } from 'vite'
|
|
549
|
+
|
|
386
550
|
export default defineConfig({
|
|
387
551
|
plugins: [foldkit(), staticSite({ site: { module: '/src/site.ts' } })],
|
|
388
552
|
})
|
|
@@ -509,8 +673,60 @@ cannot attach a handler. The browser adopts the server's markup as it is and
|
|
|
509
673
|
never runs the render, so this plan sends neither `post.title` nor `post.body`
|
|
510
674
|
and the view check still passes. A region changes only with a new document;
|
|
511
675
|
content a Message should change belongs in a Surface. A region the browser
|
|
512
|
-
needs that is not in the page, say after a Message shows one, is
|
|
513
|
-
rendered in the
|
|
676
|
+
needs that is not in the page, say after a Message shows one, is reported
|
|
677
|
+
([`StaticRegionMissing`](#diagnostics), once per page) and rendered in the
|
|
678
|
+
browser.
|
|
679
|
+
|
|
680
|
+
### What only the browser has: `prepare`
|
|
681
|
+
|
|
682
|
+
The server cannot send what it cannot see. What this browser stored (a
|
|
683
|
+
queue of writes kept in `localStorage` or IndexedDB) and what this page
|
|
684
|
+
load mints (an id its writes are named by) exist only in the browser. The
|
|
685
|
+
rule above still holds, so the first client view is the served page, and
|
|
686
|
+
such state is split by whether the view draws it:
|
|
687
|
+
|
|
688
|
+
```text
|
|
689
|
+
envelope ──▶ resumed Model ──▶ prepare: what the view does not draw ──▶ Runtime.hydrate adopts the served page
|
|
690
|
+
└─▶ a Subscription reads the store ──▶ Message ──▶ update ──▶ drawn
|
|
691
|
+
```
|
|
692
|
+
|
|
693
|
+
`prepare: model => Effect` runs once, on the Model a page resumes, before
|
|
694
|
+
anything is adopted, and the runtime starts when it succeeds. Keep it to
|
|
695
|
+
what no view draws. What the view draws arrives after, as a Message,
|
|
696
|
+
reduced over whatever the Model is by then. A `prepare` that changes what is
|
|
697
|
+
drawn makes the first client view differ from the served page: Foldkit
|
|
698
|
+
rebuilds every element that differs, and a development build warns that the
|
|
699
|
+
server DOM did not match. It must not fail, as `when` must not throw. A page
|
|
700
|
+
drawn afresh (no served page, or `otherwise: 'render'`) starts from `init`,
|
|
701
|
+
as it would without a server render, and does not run it.
|
|
702
|
+
|
|
703
|
+
Remote's durable outbox is the case it was made for. A page that makes
|
|
704
|
+
durable writes ([`foldkit-remote`'s outbox](../remote/README.md#a-write-that-outlives-the-page-outbox))
|
|
705
|
+
resumes from the outbox's `session`:
|
|
706
|
+
|
|
707
|
+
```ts
|
|
708
|
+
import { outbox } from 'foldkit-remote/outbox'
|
|
709
|
+
|
|
710
|
+
const durable = outbox(Data, { key: model => `outbox:${model.userId}`, scope: model => model.userId })
|
|
711
|
+
|
|
712
|
+
SSR.hydrate(config, plan, { buildId, prepare: durable.session })
|
|
713
|
+
```
|
|
714
|
+
|
|
715
|
+
- **The server's page holds none of the queue.** `Remote.resume` carries no
|
|
716
|
+
outbox, and the server has no store to read.
|
|
717
|
+
- **`durable.session` mints the page's id and reads nothing.** A durable
|
|
718
|
+
write made before the queue is read is queued at once, not refused.
|
|
719
|
+
- **The queue arrives through the outbox's own Subscription.** It reads the
|
|
720
|
+
store after the first frame and sends `OutboxRead`, which keeps any write
|
|
721
|
+
made before it and saves it with the rest. The unsent writes then join the
|
|
722
|
+
page, and every tab on the key shows them.
|
|
723
|
+
- **Not `durable.restore`.** As `prepare`, it would read the store before
|
|
724
|
+
adoption and show the queue in a first view the server did not draw. As
|
|
725
|
+
the config's `flags`, it never runs: a resumed page does not run `init`.
|
|
726
|
+
|
|
727
|
+
[`examples/reference`](../../examples/reference) does this on Workers: a
|
|
728
|
+
note added while the server is out of reach survives a reload of the
|
|
729
|
+
Worker's page, shows in a second tab, and is sent once the server answers.
|
|
514
730
|
|
|
515
731
|
### Markup the browser adopts: `SSR.serving`
|
|
516
732
|
|
|
@@ -559,9 +775,10 @@ const view = (model: Model, h: HtmlBuilder<Message>) => {
|
|
|
559
775
|
}
|
|
560
776
|
```
|
|
561
777
|
|
|
562
|
-
`rh` differs from `h` in
|
|
778
|
+
`rh` differs from `h` in two places: `OnInput`, `OnChange`, `OnKeyDown` and
|
|
563
779
|
`OnKeyUp` also take a Message's own constructor, and the event fills the field
|
|
564
|
-
it leaves open
|
|
780
|
+
it leaves open; and `KeepTyped` marks a field whose early typing is kept
|
|
781
|
+
([below](#typing-before-the-script-arrives)). The types check it where it is written: the member must be one
|
|
565
782
|
of the view's Messages, and leave exactly one string field, or exactly `key`
|
|
566
783
|
and `modifiers`. A closure still works. It is not data, so the page cannot
|
|
567
784
|
answer that event itself and boots on it instead, letting the live page answer.
|
|
@@ -628,7 +845,9 @@ boots it, so the Model ends where an eager boot would have taken it.
|
|
|
628
845
|
### Bundles whose code loads on demand
|
|
629
846
|
|
|
630
847
|
A `Bundle.lazy` from `foldkit-bundle` keeps a bundle's `update` and `view` out
|
|
631
|
-
of the boot chunk. Name each in the config's `lazy` list
|
|
848
|
+
of the boot chunk. Name each in the config's `lazy` list. A sketch, after
|
|
849
|
+
`test/lazyFixture.ts`: `Upload` is the lazy bundle, `PlacedUpload` its
|
|
850
|
+
placement, and `placements` their `Bundle.assemble`:
|
|
632
851
|
|
|
633
852
|
```ts
|
|
634
853
|
const config = {
|
|
@@ -651,11 +870,79 @@ meanwhile, whatever `start` says. A binding inside a placement dispatches the
|
|
|
651
870
|
parent's Message, as Foldkit's own handlers do, so the plan's Surface lists the
|
|
652
871
|
wrapper variant, `Message.GotUploadMessage`.
|
|
653
872
|
|
|
873
|
+
### Typing before the script arrives
|
|
874
|
+
|
|
875
|
+
A served page is editable as soon as it is parsed, but its script comes
|
|
876
|
+
later, and hydration re-asserts each field's value to the Model's: what was
|
|
877
|
+
typed in between would vanish. A field marked `rh.KeepTyped()` keeps it,
|
|
878
|
+
whatever the plan's `start`:
|
|
879
|
+
|
|
880
|
+
```ts
|
|
881
|
+
rh.input([rh.Value(model.draft), rh.OnInput(Message.ChangedDraft), rh.KeepTyped()])
|
|
882
|
+
```
|
|
883
|
+
|
|
884
|
+
```text
|
|
885
|
+
parse ──▶ typing (the field holds it) ──▶ script: SSR.hydrate reads the marked fields
|
|
886
|
+
──▶ each changed one becomes its OnInput Message, first in the queue
|
|
887
|
+
──▶ first render adopts the served page ──▶ value and caret put back ──▶ update
|
|
888
|
+
```
|
|
889
|
+
|
|
890
|
+
There is no inline script: the field itself holds what was typed, and an
|
|
891
|
+
`OnInput` Message carries the whole value, so the value when the script runs
|
|
892
|
+
says all the keystrokes would. A page with a Content Security Policy needs no
|
|
893
|
+
nonce for it. When the script runs, `SSR.hydrate` reads each marked field
|
|
894
|
+
whose value differs from what the server rendered and turns it into the
|
|
895
|
+
field's `OnInput` Message (else its `OnChange`), with the hole filled. These
|
|
896
|
+
go ahead of anything the page answers afterwards, once each, in document
|
|
897
|
+
order, so a page that waits to boot replays the early typing first. The first
|
|
898
|
+
render starts from the resumed Model, so it adopts every node and resets the
|
|
899
|
+
field; the field's value and selection are put back as it commits, and the
|
|
900
|
+
Message then finds the field already holding its value and writes nothing.
|
|
901
|
+
The caret stays where it was, and focus never moves. A field inside a lazy
|
|
902
|
+
bundle is replayed once the bundle's code has loaded.
|
|
903
|
+
|
|
904
|
+
Only a field the page can replay may be marked: an `input` that takes text, a
|
|
905
|
+
`textarea` or a `select`, built by `rh` (`rh.input`, not `h.input`), with
|
|
906
|
+
`OnInput` or `OnChange` given a Message member. The resumable builder marks
|
|
907
|
+
the bindings of the elements it builds; on an element `h` builds, the hole
|
|
908
|
+
forms are plain closures to the page and nothing names the Message to replay.
|
|
909
|
+
Anything else is refused on the server (`UnkeepableField`), naming the
|
|
910
|
+
element. What is not kept: an unmarked field (re-asserted to the served value,
|
|
911
|
+
as before); a key press or click before the script (the browser's own, so a
|
|
912
|
+
form submitted then posts, which `fallback: 'server'` answers); a page that is
|
|
913
|
+
contained, declined or stale; and an IME composition in progress at boot,
|
|
914
|
+
which the first render's reset ends, though its text is kept. A value the
|
|
915
|
+
browser restored into the field on a reload or a history visit is kept like
|
|
916
|
+
typing, since it is what the field shows.
|
|
917
|
+
|
|
918
|
+
`KeepTyped` answers the typing as soon as the script runs, not before. Until
|
|
919
|
+
the bundle is parsed no code of the application is in the page, so nothing
|
|
920
|
+
but the field changes: the address stays, and text derived from the query (a
|
|
921
|
+
heading, pending results) shows what the server rendered. When the script
|
|
922
|
+
runs, the replayed Message is the first `update` sees, and the page draws its
|
|
923
|
+
effects as it would any Message's. Typing is the interaction a page started
|
|
924
|
+
`'idle'` or `'on-interaction'` waits for, so such a page starts at once when
|
|
925
|
+
something was typed before its script; only a lazy bundle still loading
|
|
926
|
+
holds the queue undrawn.
|
|
927
|
+
|
|
928
|
+
Answering sooner takes code that runs before the bundle, which only an inline
|
|
929
|
+
script can be. `foldkit-ssr` writes none: it would need a Content Security
|
|
930
|
+
Policy nonce and a second copy of the field's behaviour in plain DOM code. An
|
|
931
|
+
application that keeps one (upstream's foldkit-domains writes `?q=` and fills
|
|
932
|
+
its pending cards from one) may write the address only on a page recorded for
|
|
933
|
+
its path alone (`SSR.generate`, or `SSR.entry`'s `prerendered`), which, opened
|
|
934
|
+
at another query, starts from that URL; a page rendered per request is
|
|
935
|
+
refused at any query but its own. Markup such a script changes is the
|
|
936
|
+
served page no longer, and Foldkit reconciles it at hydration to the Model's
|
|
937
|
+
first render.
|
|
938
|
+
|
|
654
939
|
## Forms that work without scripts
|
|
655
940
|
|
|
656
941
|
A form whose `OnSubmit` names a Message can be answered by the server, before
|
|
657
942
|
any script has run or with scripts blocked, because `update` is pure and the
|
|
658
|
-
server can run it.
|
|
943
|
+
server can run it. This example is a to-do list, not the post page: its Model
|
|
944
|
+
holds `draft` and `todos`, its Message `Added({ title })` and `Typed({ value
|
|
945
|
+
})`, and the `TodoList` Surface lists both. The plan opts in:
|
|
659
946
|
|
|
660
947
|
```ts
|
|
661
948
|
const Todos = SSR.plan(App, {
|
|
@@ -682,11 +969,15 @@ A form that need not work without scripts sends `Added()` and reads
|
|
|
682
969
|
|
|
683
970
|
With scripts on, nothing changes: the page answers the submit and the form
|
|
684
971
|
never posts. Without them, the server wrote the form to post the Message to the
|
|
685
|
-
page's own URL, and `SSR.entry` hands that post to `SSR.handle
|
|
972
|
+
page's own URL, and `SSR.entry` hands that post to `SSR.handle`. A form given
|
|
973
|
+
its own `Method` is left as the view draws it, with no Message field: a
|
|
974
|
+
search form is `rh.Method('get')` and sends its named fields as the address,
|
|
975
|
+
and one given `Method('post')` posts no Message, which the entry answers
|
|
976
|
+
`400`.
|
|
686
977
|
|
|
687
978
|
```text
|
|
688
979
|
POST ──▶ decode the Message ──▶ set the posted fields into it (the typed `title`)
|
|
689
|
-
──▶ init, then boot and its Commands ──▶ update, and every Command after it
|
|
980
|
+
──▶ init, prepare, then boot and its Commands ──▶ update, and every Command after it
|
|
690
981
|
──▶ the page, rendered
|
|
691
982
|
```
|
|
692
983
|
|
|
@@ -709,7 +1000,14 @@ A form a cookie session authorizes is a cross-site request forgery target,
|
|
|
709
1000
|
and a form cannot carry a CSRF header. `SSR.entry`'s `origins` names the
|
|
710
1001
|
origins a form may be posted from; a post whose `Origin` (every browser sends
|
|
711
1002
|
one on a `POST`) is not among them is answered `403` before its body is read
|
|
712
|
-
or `flags` and `resources` run.
|
|
1003
|
+
or `flags` and `resources` run. `origins: 'same-origin'` takes a post from
|
|
1004
|
+
the origin the request was addressed to and no other, for a site whose
|
|
1005
|
+
address the entry cannot know when it is made (a dev server's port). It
|
|
1006
|
+
compares with the request's own URL, so **behind a proxy that terminates TLS
|
|
1007
|
+
or rewrites the host** (nginx, Fly, Render), where the server sees
|
|
1008
|
+
`http://host` and the browser sends `Origin: https://host`, every post is
|
|
1009
|
+
refused `403`. There, pass the public origin, `origins:
|
|
1010
|
+
['https://example.com']`, never `'same-origin'`. A page served with `Referrer-Policy:
|
|
713
1011
|
no-referrer` posts `Origin: null` even to its own site; such a post, or one
|
|
714
1012
|
with no `Origin` at all, is taken when its Fetch Metadata `Sec-Fetch-Site`,
|
|
715
1013
|
which no page or form can set, says `same-origin`, and refused without it. A plan with a server fallback requires `origins`, since a post
|
|
@@ -717,61 +1015,71 @@ runs `flags`, the config's `resources` and its own as whoever the cookie says
|
|
|
717
1015
|
posted: an entry made without them throws. An entry of your own that calls
|
|
718
1016
|
`SSR.handle` checks `Origin` itself.
|
|
719
1017
|
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
A refusal never shows a user a half-working page. On the server it is an error
|
|
723
|
-
before anything is served; in the browser the page is contained, as Foldkit
|
|
724
|
-
contains a page from another build, and the reason is logged.
|
|
725
|
-
|
|
726
|
-
On the server, `SSR.render` fails with `ResumeUnsafe`, whose `reason` is one
|
|
727
|
-
of:
|
|
728
|
-
|
|
729
|
-
| `reason` | What it means | The fix |
|
|
730
|
-
| -------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------- |
|
|
731
|
-
| `ViewDependsOnUnsentState` | The view, or its head, renders differently from the browser's Model | Add the field the message names to `state`, or stop the view reading it |
|
|
732
|
-
| `UndeclaredStartup` | `init` returned Commands and the plan has no `boot` | Name them in `boot` |
|
|
733
|
-
| `Uncovered` | An active Surface reads or is activated by an unsent field, or a binding sends a Message no active Surface lists | Send the field, name it `local`, or list the Message on the Surface |
|
|
734
|
-
| `UnrestorablePart` | A part cannot restore its own capture | A bug in that part |
|
|
735
|
-
| `DuplicateStaticRegion` | Two `SSR.static` regions share an id | Give each its own id |
|
|
736
|
-
| `BindingInStaticRegion` | A handler inside an `SSR.static` region | Move the element out, into a Surface |
|
|
737
|
-
| `UndeclaredSurfaces` | The page has bindings and the plan no `surfaces` | Name the Surfaces the page may activate |
|
|
738
|
-
| `UnencodableBinding` | The plan has no Message Schema, or a binding's Message does not encode through it | Make the plan from the application; build the Message with its constructor |
|
|
739
|
-
| `EagerStartRequired` | A deferred plan would start a Subscription or Managed Resource late | Declare it in `deferrable`, or start `'now'` |
|
|
740
|
-
| `VoidRootWithStyles` | `styles` were given for a view whose root is void and holds nothing | Put the styles in the template's head with `SSR.generate`, or return an element root |
|
|
741
|
-
| `UngeneratablePath` | `SSR.generate` was given a path no file can be served at | Leave out the query and fragment; keep paths to distinct files |
|
|
742
|
-
|
|
743
|
-
In the browser, `SSR.hydrate` checks in Foldkit's order: the build id first,
|
|
744
|
-
then the envelope. `SSR.resume` reads the envelope off the stamped root and
|
|
745
|
-
returns its refusal as `ResumeRefused`: a page with no stamped root or more
|
|
746
|
-
than one, a root with no envelope (`Missing`, also for a second root as
|
|
747
|
-
`Duplicate`), `Unreadable` JSON, another `Protocol` version or `Plan`, state,
|
|
748
|
-
parts or bindings that are `Invalid`, or a `Route` other than the one the page
|
|
749
|
-
was rendered for. A page is resumed whole or not at all.
|
|
750
|
-
|
|
751
|
-
### A page the browser does not take over
|
|
1018
|
+
### Answering a post with a redirect
|
|
752
1019
|
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
1020
|
+
The page a post renders sits at the address the form posted to, so a reload
|
|
1021
|
+
asks to post again. That is harmless for an idempotent Message and wrong for
|
|
1022
|
+
one that orders or sends something. `answerPost: 'redirect'` answers the post
|
|
1023
|
+
`303` to the same address instead, and the browser asks for it with a `GET`
|
|
1024
|
+
(Post/Redirect/Get):
|
|
758
1025
|
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
satisfies `until`, it takes the page's place in one step, with the served
|
|
764
|
-
page's id. It never waits longer than `UNTIL_LIMIT_MS` (3 s). The CMS site
|
|
765
|
-
(`examples/cms/src/ssr/sitePlan.ts`) declines a page opened by an author, and
|
|
766
|
-
waits for the route's read and its Blocks' reads, which its `Site.answered`
|
|
767
|
-
checks with `RemoteData.answered` and `QueryBlock.active(...).answered`:
|
|
1026
|
+
```text
|
|
1027
|
+
POST /todos ──▶ update, and its Commands ──▶ 303, Location: /todos, headers(request, some(model))
|
|
1028
|
+
GET /todos ──▶ init, prepare ──▶ the page, rendered
|
|
1029
|
+
```
|
|
768
1030
|
|
|
769
1031
|
```ts
|
|
770
|
-
SSR.
|
|
1032
|
+
SSR.entry(config, Todos, {
|
|
1033
|
+
buildId,
|
|
1034
|
+
origins: ['https://example.com'],
|
|
1035
|
+
answerPost: 'redirect',
|
|
1036
|
+
// What the post changed has to outlive it: the next request starts from `init`.
|
|
1037
|
+
headers: (_request, model) =>
|
|
1038
|
+
Option.match(model, {
|
|
1039
|
+
onNone: () => ({}),
|
|
1040
|
+
onSome: ({ todos }) => ({
|
|
1041
|
+
'set-cookie': `todos=${encodeURIComponent(JSON.stringify(todos))}; Path=/; HttpOnly; SameSite=Lax`,
|
|
1042
|
+
}),
|
|
1043
|
+
}),
|
|
1044
|
+
})
|
|
771
1045
|
```
|
|
772
1046
|
|
|
773
|
-
The
|
|
774
|
-
|
|
1047
|
+
The `Location` is the posted address's path and query, relative, so the
|
|
1048
|
+
browser resolves it against the address it posted to and it can name no
|
|
1049
|
+
other origin, whatever `Host` the request claimed. The `GET` starts from
|
|
1050
|
+
`init` and `prepare`, so whatever the post changed reaches it only through
|
|
1051
|
+
what `headers` wrote (a cookie) or a store of the application's; `prepare`
|
|
1052
|
+
reads it back. The page shows nothing else of the post: a message about its
|
|
1053
|
+
outcome is a one-shot cookie the application writes and `prepare` reads. A
|
|
1054
|
+
refused post is still a `400`, and a failing Command a `500`.
|
|
1055
|
+
|
|
1056
|
+
### A whole page without scripts
|
|
1057
|
+
|
|
1058
|
+
A form that posts is one part of a page that works with JavaScript off. The
|
|
1059
|
+
rest is the application's, and
|
|
1060
|
+
[`examples/foldkit/domains-plus`](../../examples/foldkit/domains-plus) does
|
|
1061
|
+
all of it; [Pages that work without JavaScript](../../docs/progressive-enhancement.md)
|
|
1062
|
+
is the guide. What the port needed from this package:
|
|
1063
|
+
|
|
1064
|
+
- **Render what is shown.** `SSR.render` fetches nothing, so read first, in
|
|
1065
|
+
`prepare` (`Data.satisfy`); send the reading
|
|
1066
|
+
Surfaces' data with `parts: [Remote.resume(Data)]` and list the Surfaces
|
|
1067
|
+
in `surfaces`, so the browser reads none of it again.
|
|
1068
|
+
- **Give a GET form its method.** With a fallback, a form `rh` builds whose
|
|
1069
|
+
`OnSubmit` names a Message posts it; a search or filter form is a GET of
|
|
1070
|
+
the address the URL mirror reads, and `rh.Method('get')` leaves it one.
|
|
1071
|
+
- **Draw the plain controls on both sides.** Show them under
|
|
1072
|
+
`@media (scripting: none)` and hide the scripted ones there; a control in
|
|
1073
|
+
`<noscript>` is not drawn by the view, and the page would not be the one
|
|
1074
|
+
the browser renders first.
|
|
1075
|
+
- **Keep state between posts yourself.** A post starts from `init`, so what
|
|
1076
|
+
must outlive it lives in a cookie the entry reads in `prepare`, validated
|
|
1077
|
+
as it is read, and `headers(request, model)` writes it back from the Model
|
|
1078
|
+
the post reached. With that, answer posts with a redirect
|
|
1079
|
+
(`answerPost: 'redirect'`), so a reload does not post again.
|
|
1080
|
+
- **Wait for the takeover in a scripted test.** The served page works on its
|
|
1081
|
+
own, so a click before boot posts. The root loses `data-foldkit-plus-resume`
|
|
1082
|
+
as the page boots.
|
|
775
1083
|
|
|
776
1084
|
## A reader's preferences in the first frame
|
|
777
1085
|
|
|
@@ -835,6 +1143,97 @@ catches up in `boot`. `foldkit-mixins/theme` ships the pairs: `schemeScript`
|
|
|
835
1143
|
and `chooseScheme`, `Themes.script` and `Themes.choose`, `Theme.knobScript`
|
|
836
1144
|
and `Theme.chooseKnobs`.
|
|
837
1145
|
|
|
1146
|
+
## When a page is refused
|
|
1147
|
+
|
|
1148
|
+
A refusal never shows a user a half-working page. On the server it is an error
|
|
1149
|
+
before anything is served; in the browser the page is contained, as Foldkit
|
|
1150
|
+
contains a page from another build, and the reason is reported
|
|
1151
|
+
([`PageContained`](#diagnostics)).
|
|
1152
|
+
|
|
1153
|
+
On the server, `SSR.render` fails with `ResumeUnsafe`, whose `reason` is one
|
|
1154
|
+
of:
|
|
1155
|
+
|
|
1156
|
+
| `reason` | What it means | The fix |
|
|
1157
|
+
| -------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------- |
|
|
1158
|
+
| `ViewDependsOnUnsentState` | The view, or its head, renders differently from the browser's Model | Add the field the message names to `state`, or stop the view reading it |
|
|
1159
|
+
| `UndeclaredStartup` | `init` returned Commands and the plan has no `boot` | Name them in `boot` |
|
|
1160
|
+
| `Uncovered` | An active Surface reads or is activated by an unsent field, or a binding sends a Message no active Surface lists | Send the field, name it `local`, or list the Message on the Surface |
|
|
1161
|
+
| `UnrestorablePart` | A part cannot restore its own capture | A bug in that part |
|
|
1162
|
+
| `DuplicateStaticRegion` | Two `SSR.static` regions share an id | Give each its own id |
|
|
1163
|
+
| `BindingInStaticRegion` | A handler inside an `SSR.static` region | Move the element out, into a Surface |
|
|
1164
|
+
| `UndeclaredSurfaces` | The page has bindings and the plan no `surfaces` | Name the Surfaces the page may activate |
|
|
1165
|
+
| `UnencodableBinding` | The plan has no Message Schema, or a binding's Message does not encode through it | Make the plan from the application; build the Message with its constructor |
|
|
1166
|
+
| `EagerStartRequired` | A deferred plan would start a Subscription or Managed Resource late | Declare it in `deferrable`, or start `'now'` |
|
|
1167
|
+
| `VoidRootWithStyles` | `styles` were given for a view whose root is void and holds nothing | Put the styles in the template's head with `SSR.generate`, or return an element root |
|
|
1168
|
+
| `UnkeepableField` | `KeepTyped` on an element that holds no typed value, one `h` built rather than `rh`, or with no `OnInput`/`OnChange` given a Message member | Mark only a text `input`, `textarea` or `select` that `rh` builds, and give its binding the Message's member |
|
|
1169
|
+
| `UngeneratablePath` | `SSR.generate` was given a path no file can be served at | Leave out the query and fragment; keep paths to distinct files |
|
|
1170
|
+
|
|
1171
|
+
In the browser, `SSR.hydrate` checks in Foldkit's order: the build id first,
|
|
1172
|
+
then the envelope. `SSR.resume` reads the envelope off the stamped root and
|
|
1173
|
+
returns its refusal as `ResumeRefused`: a page with no stamped root or more
|
|
1174
|
+
than one, a root with no envelope (`Missing`, also for a second root as
|
|
1175
|
+
`Duplicate`), `Unreadable` JSON, another `Protocol` version or `Plan`, state,
|
|
1176
|
+
parts or bindings that are `Invalid`, or a `Route` other than the one the page
|
|
1177
|
+
was rendered for. A page is resumed whole or not at all.
|
|
1178
|
+
|
|
1179
|
+
### A page the browser does not take over
|
|
1180
|
+
|
|
1181
|
+
A page can be declined before anything is adopted: `when(document)` says
|
|
1182
|
+
whether to take it over (a page rendered for a visitor, opened by an author),
|
|
1183
|
+
and `fresh(plan.version)` whether its data is still current. A declined or
|
|
1184
|
+
stale page is contained, as a refused one is, unless `otherwise: 'render'`
|
|
1185
|
+
runs the application afresh in its place.
|
|
1186
|
+
|
|
1187
|
+
Drawn afresh at once, the page would show the fresh application's first draw,
|
|
1188
|
+
usually its loading state, until its reads answer: the page blinks to "Loading"
|
|
1189
|
+
and back. `until(model)` keeps the served page in view meanwhile. The fresh
|
|
1190
|
+
application draws in a hidden element beside it, and when a Model it has drawn
|
|
1191
|
+
satisfies `until`, it takes the page's place in one step, with the served
|
|
1192
|
+
page's id. It never waits longer than `UNTIL_LIMIT_MS` (3 s). The CMS site
|
|
1193
|
+
(`examples/cms/src/ssr/sitePlan.ts`) declines a page opened by an author, and
|
|
1194
|
+
waits for the route's read and its Blocks' reads, which its `Site.answered`
|
|
1195
|
+
checks with `RemoteData.answered` and `QueryBlock.active(...).answered`:
|
|
1196
|
+
|
|
1197
|
+
```ts
|
|
1198
|
+
SSR.hydrate(config, plan, { buildId, when, otherwise: 'render', until: Site.answered })
|
|
1199
|
+
```
|
|
1200
|
+
|
|
1201
|
+
The served page stays as it was served while it waits: its links are plain
|
|
1202
|
+
links, and nothing it shows becomes live.
|
|
1203
|
+
|
|
1204
|
+
## Diagnostics
|
|
1205
|
+
|
|
1206
|
+
What SSR meets and keeps going past, a page it contains or a request it
|
|
1207
|
+
answers `500`, is a typed diagnostic, reported through `Diagnostics.Reporter`
|
|
1208
|
+
(`foldkit-surface`'s channel, re-exported here), which by default is
|
|
1209
|
+
Effect's log: the browser's console, or a server's or Worker's log.
|
|
1210
|
+
|
|
1211
|
+
| `_tag` | `level` | When |
|
|
1212
|
+
| --------------------- | --------- | ------------------------------------------------------------------------------------------------------------- |
|
|
1213
|
+
| `PageContained` | `error` | The browser contained the page instead of resuming it: `reason` is `NoBuildId`, `OtherBuild` or the `ResumeRefused` reason |
|
|
1214
|
+
| `StaticRegionMissing` | `error` | A static region the browser drew is not in the server's page, so it was rendered in the browser (`region`) |
|
|
1215
|
+
| `BundleUnloaded` | `error` | A lazy bundle's bodies did not load, and the page booted without them (`error`) |
|
|
1216
|
+
| `PageFailed` | `error` | `SSR.entry` answered `500`: `headers` threw, or the page could not be rendered (`url`, `cause`) |
|
|
1217
|
+
| `HandlerUnnamed` | `warning` | A handler the page cannot name keeps a page that waits to boot from answering it, once per process |
|
|
1218
|
+
|
|
1219
|
+
A page's refusals happen before any runtime starts, so the reporter in its
|
|
1220
|
+
`resources` is not in effect yet: `SSR.hydrate` takes its own. `SSR.entry`
|
|
1221
|
+
takes one with the request beside it, used for everything that request runs, a
|
|
1222
|
+
posted form's Commands included. `SSR.generate` reports to the reporter in
|
|
1223
|
+
its Effect's context.
|
|
1224
|
+
|
|
1225
|
+
```ts
|
|
1226
|
+
SSR.hydrate(config, plan, { buildId, diagnostics: diagnostic => send(diagnostic) })
|
|
1227
|
+
|
|
1228
|
+
SSR.entry(config, plan, {
|
|
1229
|
+
buildId,
|
|
1230
|
+
diagnostics: (diagnostic, request) =>
|
|
1231
|
+
Effect.logError(`${request.method} ${request.url}: ${diagnostic.message}`),
|
|
1232
|
+
})
|
|
1233
|
+
```
|
|
1234
|
+
|
|
1235
|
+
In a test, `Diagnostics.collect()` gives a reporter and the array it fills.
|
|
1236
|
+
|
|
838
1237
|
## Costs and limits
|
|
839
1238
|
|
|
840
1239
|
- **`SSR.render` renders the view twice.** That is the view check. A static
|
|
@@ -848,16 +1247,26 @@ and `Theme.chooseKnobs`.
|
|
|
848
1247
|
- **A resumable page leans on two Foldkit behaviours,** each pinned by a test
|
|
849
1248
|
here and by Foldkit's own: the first patch removes attributes the browser's
|
|
850
1249
|
view does not assert, and a control's value is re-asserted to the Model's.
|
|
1250
|
+
What the server wrote for the browser's script alone (the envelope, the
|
|
1251
|
+
markers, a placement's slot, a fallback form's method and hidden field) is
|
|
1252
|
+
taken off as the page boots, before Foldkit records the served page, so a
|
|
1253
|
+
development build does not report it as markup the view disagrees with.
|
|
851
1254
|
It does not depend on `Runtime.hydrate` rendering its first frame before
|
|
852
1255
|
it returns, which Foldkit does today without promising it: until that
|
|
853
1256
|
frame commits (`Render.afterCommit`), the page keeps answering from its
|
|
854
1257
|
markers and sends the live page what only it can answer.
|
|
1258
|
+
- **A kept field is written twice at boot.** Hydration re-asserts the served
|
|
1259
|
+
value, and the page writes the typed one back with its selection, in the
|
|
1260
|
+
same task, so nothing paints between. The write ends an IME composition
|
|
1261
|
+
in progress; leaving a changed control alone is
|
|
1262
|
+
[proposal 6](../../docs/upstream-foldkit-ssr.md#proposal-6-leave-a-control-the-person-changed-alone-at-hydration).
|
|
855
1263
|
- **Development is not production.** Under Vite's dev server, Foldkit's model
|
|
856
1264
|
preservation restores the previous Model after a reload and skips adoption.
|
|
857
1265
|
- **A closure handler makes its event wait for boot.** `SSR.render`'s result
|
|
858
1266
|
lists each under `unnamed` (`{ element: 'button#point', event:
|
|
859
1267
|
'pointerdown' }`), and on a page that waits to boot `SSR.entry` and
|
|
860
|
-
`SSR.generate`
|
|
1268
|
+
`SSR.generate` report each once per process (`HandlerUnnamed`), naming
|
|
1269
|
+
the fix.
|
|
861
1270
|
|
|
862
1271
|
## Lower-level API
|
|
863
1272
|
|
|
@@ -868,8 +1277,8 @@ and `Theme.chooseKnobs`.
|
|
|
868
1277
|
as a `Result`. `SSR.render` carries it on the stamped root, beside Foldkit's
|
|
869
1278
|
own stamps; the JSON escapes `<` as Foldkit escapes its Flags, and U+2028
|
|
870
1279
|
and U+2029, and the attribute escapes `&` and `"` besides, so no string in
|
|
871
|
-
the Model can break out of the value.
|
|
872
|
-
|
|
1280
|
+
the Model can break out of the value. The browser reads it, then takes the
|
|
1281
|
+
attribute off as the page boots.
|
|
873
1282
|
- **`SSR.inspect(plan, model)`**: the plan's coverage as data.
|
|
874
1283
|
- **`Resume.bindings(plan, document, root, model)`** decodes and checks a
|
|
875
1284
|
page's bindings, and **`Resume.listen(root, { bindings, onAnswer, events? })`**
|
|
@@ -881,20 +1290,22 @@ and `Theme.chooseKnobs`.
|
|
|
881
1290
|
- **Attribute names**, for tools and tests: `RESUME_ATTRIBUTE` (the envelope
|
|
882
1291
|
on the stamped root), `STATIC_ATTRIBUTE`, `BINDING_ATTRIBUTE` (a prefix,
|
|
883
1292
|
followed by the event), `SLOT_ATTRIBUTE` (a placement's root while the server
|
|
884
|
-
renders)
|
|
1293
|
+
renders), `KEEP_ATTRIBUTE` (a kept field, naming the binding that replays
|
|
1294
|
+
it) and `FALLBACK_FIELD` (the posted Message).
|
|
885
1295
|
|
|
886
1296
|
## The application in these examples
|
|
887
1297
|
|
|
888
1298
|
A post page. `App` is `Surface.application({ Model, Message, initial, update
|
|
889
1299
|
})`. The Surfaces (`PostActions`, `Menu`, `Like`), `Data` (a `Remote.make`
|
|
890
1300
|
domain over `App.model.remote`) and `LoadPreferences` (a `Command.define`) are
|
|
891
|
-
the application's own
|
|
1301
|
+
the application's own; a Surface a resumable page dispatches from lists its
|
|
1302
|
+
Messages (`messages: [Message.Liked]`). `PostActionsAt` and `PostPageAt` are Surfaces placed
|
|
892
1303
|
for a plan, as `Surface.when(PostActions, App.model.route, AppRoute.Post, route
|
|
893
1304
|
=> ({ id: route.id }))` places one in
|
|
894
1305
|
[the coverage example](#checking-what-the-browser-will-read).
|
|
895
1306
|
|
|
896
1307
|
```ts
|
|
897
|
-
const AppRoute = defineRouteUnion({ Home: {}, Post: { id: Schema.String } })
|
|
1308
|
+
const AppRoute = defineRouteUnion({ Home: {}, Post: { id: Schema.String }, NotFound: {} })
|
|
898
1309
|
|
|
899
1310
|
const Model = Schema.Struct({
|
|
900
1311
|
route: AppRoute,
|
|
@@ -902,6 +1313,8 @@ const Model = Schema.Struct({
|
|
|
902
1313
|
id: Schema.String,
|
|
903
1314
|
title: Schema.String,
|
|
904
1315
|
body: Schema.String,
|
|
1316
|
+
excerpt: Schema.String,
|
|
1317
|
+
publishedAt: Schema.String,
|
|
905
1318
|
liked: Schema.Boolean,
|
|
906
1319
|
}),
|
|
907
1320
|
draft: Schema.String,
|