foldkit-remote-server 0.18.0 → 0.20.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 +527 -156
- package/dist/fetch.d.mts +38 -3
- package/dist/fetch.d.mts.map +1 -1
- package/dist/fetch.mjs +70 -29
- package/dist/fetch.mjs.map +1 -1
- package/dist/index-B85UhEfk.d.mts +998 -0
- package/dist/index-B85UhEfk.d.mts.map +1 -0
- package/dist/index.d.mts +2 -670
- package/dist/index.mjs +1 -1
- package/dist/{src-yDMwdGiL.mjs → src-D8azLxgd.mjs} +741 -106
- package/dist/src-D8azLxgd.mjs.map +1 -0
- package/package.json +9 -9
- package/dist/index.d.mts.map +0 -1
- package/dist/src-yDMwdGiL.mjs.map +0 -1
package/README.md
CHANGED
|
@@ -66,6 +66,13 @@ That separation matters. `RemoteServer` can decide that a client may read
|
|
|
66
66
|
that field comes from Postgres, another service, an in-memory index, or
|
|
67
67
|
something else.
|
|
68
68
|
|
|
69
|
+
It does **not** own HTTP or WebSocket transport, authentication or session
|
|
70
|
+
storage, a database connection, the client's normalized cache, or Surface
|
|
71
|
+
activation. A durable write is the client's to keep (Remote's outbox) and the
|
|
72
|
+
writer's to recognise when it comes again (a ledger); this package only passes
|
|
73
|
+
its operation id through. Client-authored state that must merge across devices
|
|
74
|
+
is [`foldkit-sync`](../sync)'s.
|
|
75
|
+
|
|
69
76
|
## Install
|
|
70
77
|
|
|
71
78
|
```bash
|
|
@@ -297,10 +304,10 @@ const ProjectsByOwner = Query.make('ProjectsByOwner', {
|
|
|
297
304
|
Result: Query.connection(Project),
|
|
298
305
|
})
|
|
299
306
|
|
|
307
|
+
// `projectsPage` is your own reader: one page of edges for the window.
|
|
300
308
|
const ProjectsByOwnerSource = RemoteServer.query(
|
|
301
309
|
ProjectsByOwner,
|
|
302
|
-
({ input, window, principal,
|
|
303
|
-
projectsPage({ ownerId: input.ownerId, window, principal }),
|
|
310
|
+
({ input, window, principal }) => projectsPage({ ownerId: input.ownerId, window, principal }),
|
|
304
311
|
)
|
|
305
312
|
|
|
306
313
|
const Server = RemoteServer.make({
|
|
@@ -311,7 +318,7 @@ const Server = RemoteServer.make({
|
|
|
311
318
|
|
|
312
319
|
A Query returns:
|
|
313
320
|
|
|
314
|
-
```ts
|
|
321
|
+
```ts sketch
|
|
315
322
|
{
|
|
316
323
|
edges,
|
|
317
324
|
start,
|
|
@@ -330,78 +337,13 @@ of guessing from row count.
|
|
|
330
337
|
|
|
331
338
|
Query input is decoded through the Query's own Schema before your callback runs.
|
|
332
339
|
The callback receives the decoded input, the requested `QueryWindow`, the
|
|
333
|
-
`select` slice when the client sent one, and the
|
|
334
|
-
|
|
335
|
-
### Running a query body over rows you already hold
|
|
336
|
-
|
|
337
|
-
A descriptor declared with
|
|
338
|
-
[`Query.define`](../remote#queries-and-pagination) carries its meaning as a
|
|
339
|
-
value, and `evaluate` runs that value directly:
|
|
340
|
-
|
|
341
|
-
```ts
|
|
342
|
-
import { evaluate } from 'foldkit-entity'
|
|
343
|
-
|
|
344
|
-
evaluate(PostsBySlug.body!, { slug: 'intro' }, rows)
|
|
345
|
-
// the matching rows, in the order the body asks for
|
|
346
|
-
```
|
|
347
|
-
|
|
348
|
-
It lives in [`foldkit-entity`](../entity), beside the IR it interprets, because
|
|
349
|
-
it is that IR's reference semantics rather than anything this package does —
|
|
350
|
-
and because a client judging rows it already holds needs it without depending on
|
|
351
|
-
a server package. This package re-exports it, so importing it from either place
|
|
352
|
-
means the same thing.
|
|
353
|
-
|
|
354
|
-
It is pure — it reads the rows it is given and nothing else — and it is the
|
|
355
|
-
reference the compiled interpreters are checked against. `foldkit-remote-drizzle`
|
|
356
|
-
turns the same body into SQL; the test suite runs both over the same rows in a
|
|
357
|
-
real SQLite and requires the same ids in the same order. That is what makes a
|
|
358
|
-
body source-neutral in fact rather than in principle.
|
|
359
|
-
|
|
360
|
-
**It follows SQL, not JavaScript.** The case that matters is null: `null = null`
|
|
361
|
-
is *unknown* in SQL and matches no row, where JavaScript would call the two
|
|
362
|
-
equal. A comparison keeps a row only when it is true, so a null on either side
|
|
363
|
-
drops it.
|
|
364
|
-
|
|
365
|
-
What it refuses rather than guesses:
|
|
366
|
-
|
|
367
|
-
- **Ordering by a column that is null in some row.** SQLite sorts nulls first,
|
|
368
|
-
Postgres sorts them last for `asc`: the databases disagree with each other, so
|
|
369
|
-
there is no answer to be conformant to and picking one would make this wrong
|
|
370
|
-
against the other.
|
|
371
|
-
- **Comparing values it has no order for**, such as a number against a string.
|
|
372
|
-
- **Searching text that holds a NUL character**, which Postgres text cannot
|
|
373
|
-
hold and SQLite's `like` stops at.
|
|
374
|
-
|
|
375
|
-
Each throws where the query runs, naming the query. An ordering is checked
|
|
376
|
-
before anything is sorted: every term over every matched row, in row order, so
|
|
377
|
-
the error names the first row that breaks it (`number and string` when a later
|
|
378
|
-
row holds text), the same on every engine, whichever pair a sort would have
|
|
379
|
-
compared first. One matched row, or none, has nothing to order and is never
|
|
380
|
-
refused.
|
|
381
|
-
|
|
382
|
-
### Checking an interpreter against the semantics
|
|
383
|
-
|
|
384
|
-
`evaluate` is the reference, and `cases` is what it is a reference *to*: the
|
|
385
|
-
conformance suite, exported so an interpreter written elsewhere can be held to
|
|
386
|
-
the same semantics.
|
|
387
|
-
|
|
388
|
-
```ts
|
|
389
|
-
import { Subject, cases, rows } from 'foldkit-remote-server'
|
|
390
|
-
|
|
391
|
-
for (const { what, body, input, expected } of cases) {
|
|
392
|
-
expect(yourInterpreter(body, input, rows).map(row => row.id)).toEqual(expected)
|
|
393
|
-
}
|
|
394
|
-
```
|
|
340
|
+
`select` slice when the client sent one, the principal, and the server's
|
|
341
|
+
`viewer` of it.
|
|
395
342
|
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
`
|
|
399
|
-
|
|
400
|
-
package meaning three different things because every value in the original
|
|
401
|
-
fixture happened to be lowercase.
|
|
402
|
-
|
|
403
|
-
Both interpreters here run it: this package over rows in memory, and
|
|
404
|
-
`foldkit-remote-drizzle` compiled to SQL against a real SQLite.
|
|
343
|
+
A query declared with `Query.define` carries its meaning as a value, so it
|
|
344
|
+
needs no hand-written Source: `RemoteServer.memory` runs its body with
|
|
345
|
+
`evaluate`, and `foldkit-remote-drizzle` compiles it to SQL (see [Reference
|
|
346
|
+
semantics](#reference-semantics-evaluate-and-the-conformance-suite)).
|
|
405
347
|
|
|
406
348
|
## Mutations
|
|
407
349
|
|
|
@@ -418,6 +360,7 @@ const RenameProject = Mutation.make('RenameProject', {
|
|
|
418
360
|
Output: Schema.Struct({ id: Schema.String }),
|
|
419
361
|
})
|
|
420
362
|
|
|
363
|
+
// `renameProject` is your own write, answering the Output.
|
|
421
364
|
const RenameProjectSource = RemoteServer.mutation(
|
|
422
365
|
RenameProject,
|
|
423
366
|
({ input, principal }) =>
|
|
@@ -443,14 +386,15 @@ A refusal of who is asking, rather than of what they asked, is
|
|
|
443
386
|
`Effect.fail(RemoteServer.forbid('Only an admin may archive.'))`: sent as
|
|
444
387
|
`Forbidden` with the reason (a 403 over JSON), or with none when `forbid()` is
|
|
445
388
|
given none, so the refusal says nothing of why. It is the same for every
|
|
446
|
-
mutation, so it needs no `Refusal` declared.
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
389
|
+
mutation, so it needs no `Refusal` declared. A refusal of a visitor, someone
|
|
390
|
+
not signed in, is `RemoteServer.unauthenticated(reason)` instead (a 401):
|
|
391
|
+
signing in is the remedy, and Remote's outbox keeps a durable write so
|
|
392
|
+
answered waiting for it, where it settles a `Forbidden` one as failed.
|
|
393
|
+
`RemoteServer.write` refuses a visitor a write whose Entity sets a member from
|
|
394
|
+
who asks that way, and `GuardServer` refuses a visitor every write it would
|
|
395
|
+
refuse.
|
|
396
|
+
|
|
397
|
+
A Source may additionally return connection changes:
|
|
454
398
|
|
|
455
399
|
```ts
|
|
456
400
|
RemoteServer.prepend(connection, Project.ref(id))
|
|
@@ -461,49 +405,124 @@ RemoteServer.remove(connection, Project.ref(id))
|
|
|
461
405
|
Those confirmed changes replace the corresponding optimistic connection layers
|
|
462
406
|
on the client.
|
|
463
407
|
|
|
408
|
+
### A write sent again: `operation`
|
|
409
|
+
|
|
410
|
+
The Source is also given `requestId`, the client's id for the request, and
|
|
411
|
+
`operation`, the operation's id across clients, both the same on every retry of
|
|
412
|
+
it. Record a write under `operation`, never `requestId`: a request id is a
|
|
413
|
+
counter in one client's Model, so two clients' first requests share it, and a
|
|
414
|
+
record keyed by it would answer one client with another's write. `operation`
|
|
415
|
+
is none from a client that sends none, and bounded on the wire (128
|
|
416
|
+
characters of `A-Z a-z 0-9 : . _ -`).
|
|
417
|
+
|
|
418
|
+
Expect the same operation more than once. A write that no answer came back
|
|
419
|
+
for fails on the client with `Unreachable` (`RemoteUnreachable`): the request
|
|
420
|
+
did not go, or what came back was no Remote answer (not JSON, or under a 408,
|
|
421
|
+
429, 502, 503 or 504, which this package never answers with but a gateway or
|
|
422
|
+
a rate limiter may). The server may have landed it. `Data.retry` sends it
|
|
423
|
+
again under the same operation, and a durable write (`Data.mutate(…, {
|
|
424
|
+
durable: true })`) is stored in the page's outbox and sent again on its own,
|
|
425
|
+
after an `Unreachable` and after a reload, with the same operation id and the
|
|
426
|
+
same `now`. What a retry does depends on the write: setting a value sets it
|
|
427
|
+
again, an `expect`ed revision answers `Conflict`, and only a ledger (below)
|
|
428
|
+
recognises the operation and answers it from its record. A durable Mutation
|
|
429
|
+
therefore needs a writer with a ledger, or a handler that records by
|
|
430
|
+
`operation`.
|
|
431
|
+
|
|
432
|
+
The outbox never sends one principal's waiting writes as another's: it holds
|
|
433
|
+
its queue for one store key and scope, and sends none of it once either
|
|
434
|
+
changes. The server still decides each send as whoever that request
|
|
435
|
+
authenticates as.
|
|
436
|
+
|
|
437
|
+
### Declared writes: no handler
|
|
438
|
+
|
|
464
439
|
A mutation declared as a `Write` (`Mutation.write`) needs no handler.
|
|
465
440
|
`RemoteServer.write(mutation, writer)` binds the input to the write, only the
|
|
466
441
|
keys the client named when it named some, and hands the row's id and new values
|
|
467
442
|
to an `EntityWriter`, which writes them and answers the row as written:
|
|
468
443
|
|
|
469
444
|
```ts
|
|
470
|
-
|
|
445
|
+
// `EditProject` is a Mutation.write; `writer` and the binding `Db` are foldkit-remote-drizzle's.
|
|
446
|
+
RemoteServer.write(EditProject, writer(Db.Project))
|
|
471
447
|
```
|
|
472
448
|
|
|
473
|
-
The answer is the mutation's patch, or for a delete its deletion.
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
`
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
449
|
+
The answer is the mutation's patch, or for a delete its deletion. The writer
|
|
450
|
+
must be for the write's own Entity, which is checked where the mutation is
|
|
451
|
+
served. The [declared writes guide](../../docs/declared-writes.md) walks
|
|
452
|
+
through the whole path; what this package does with each part of a write:
|
|
453
|
+
|
|
454
|
+
- **What the server chooses.** A write of an Entity with `Entity.sets` is
|
|
455
|
+
handed the members its context sets as well, never from the input (an
|
|
456
|
+
insert all of them, an update those set `on: 'write'`): `Expr.viewer` from
|
|
457
|
+
`RemoteServer.make({ viewer: principal => Option<{ entity, id }> })`, and
|
|
458
|
+
`Expr.now` from the write's time. A value that comes to null where the
|
|
459
|
+
member holds none (a visitor's) is refused as forbidden; a server that
|
|
460
|
+
serves a write setting the viewer with no `viewer` is refused where it is
|
|
461
|
+
made. A path from the viewer is read through the server's own sources, as
|
|
462
|
+
the asker may see each row (the run context's `read`); a server that mounts
|
|
463
|
+
no source for a row the path reaches is refused where it is made, and a
|
|
464
|
+
path reaching no row the asker may see is null.
|
|
465
|
+
- **The write's time** is the client's when it sent one (`Data.mutate`'s
|
|
466
|
+
`now`, the moment the reader acted, which the client showed the row at) and
|
|
467
|
+
it lies within `RemoteServer.make({ clockSkew })` of the server's Effect
|
|
468
|
+
`Clock`: 60 seconds unless given, `0` to never take a client's time.
|
|
469
|
+
Otherwise it is the server's own, and a time past a bound above zero is
|
|
470
|
+
reported as a `ClockSkewed` diagnostic: a durable write sent long after it
|
|
471
|
+
was made takes the server's time. The bound is how far a client can backdate
|
|
472
|
+
or postdate a row; nothing else of a write's context comes from the client.
|
|
473
|
+
A hand-written mutation reads the same time as `now` in its context. A
|
|
474
|
+
retried insert, which only a writer's ledger recognises, keeps its first
|
|
475
|
+
time. A retried update is a new write to a server without a ledger, and
|
|
476
|
+
stores the time of the attempt that ran: the same sent `now` while it lies
|
|
477
|
+
within `clockSkew`, else the server's clock at that attempt (#291). A ledger
|
|
478
|
+
answers the retry from its record, so the first time stays.
|
|
479
|
+
- **`expect`**: the writer is told the revision the row was read at; no row
|
|
480
|
+
at it is refused as `Refusal.conflict`.
|
|
481
|
+
- **`when`**: the writer is handed the precondition and the input encoded,
|
|
482
|
+
checks it in the statement that writes, and fails a row at the revision
|
|
483
|
+
that does not hold it with `RemoteUnmet` (`RemoteServer.unmet()`), refused
|
|
484
|
+
as `Refusal.unmet`: absent first, then a moved revision, then the
|
|
485
|
+
precondition.
|
|
486
|
+
- **Invariants** (`Entity.invariant`) are the writer's to judge over the row
|
|
487
|
+
the write would leave, refusing with `RemoteServer.invalid(message, rule,
|
|
488
|
+
path)`, sent as `Refusal.invalid`: the invariant's id and path, or none and
|
|
489
|
+
empty when the caller may not be told them.
|
|
490
|
+
- **Increments and computed assignments** reach the writer apart from its
|
|
491
|
+
values (`increments`, each field's amount, encoded; `assignments`, each a
|
|
492
|
+
`Computation`), to be applied in the statement that writes. One that
|
|
493
|
+
expects no revision is served only over a writer with a ledger, and only
|
|
494
|
+
for a request carrying an operation id; even so, a concurrent pair must land
|
|
495
|
+
as one result: an increment only of an integer, and a computed assignment
|
|
496
|
+
only where the writer `commutes` it, unless the writer pins the row it read
|
|
497
|
+
(`pins: true`, a guard with a revision).
|
|
498
|
+
- **A rule over another row.** A writer that holds an update's or a delete's
|
|
499
|
+
row to a `requires` (`RowRequirement`: bodies over the row, all or any of
|
|
500
|
+
them) in its own statement refuses a row that fails it with `Forbidden`:
|
|
501
|
+
`foldkit-guard` hands it a rule that reads another row that way.
|
|
502
|
+
- **Creates and deletes.** An update of no row fails, and a delete of a row
|
|
503
|
+
already gone succeeds, so its retry is safe. An insert of an id already
|
|
504
|
+
taken is refused as `Refusal.taken` (the writer fails `insert` with
|
|
505
|
+
`RemoteTaken`, `RemoteServer.taken()`), with one answer whatever the row
|
|
506
|
+
there holds and whether its asker may see it: comparing that row with the
|
|
507
|
+
insert would tell the asker what it holds. Only a writer with a ledger tells a retry from another create
|
|
508
|
+
of the id, by the operation the client sent, and answers it with the row;
|
|
509
|
+
without one, a create whose answer was lost is refused when it is sent
|
|
510
|
+
again. Give a writer a ledger where a client may resend a create, and make
|
|
511
|
+
ids that a guess cannot find where whether a row exists is itself private.
|
|
512
|
+
|
|
513
|
+
A writer says what it can do, and `RemoteServer.write` refuses, where the
|
|
514
|
+
write is served, one that needs what its writer lacks rather than writing it
|
|
515
|
+
wrongly:
|
|
516
|
+
|
|
517
|
+
| `EntityWriter` says | It | Needed by |
|
|
518
|
+
| --- | --- | --- |
|
|
519
|
+
| `preconditions: true` | checks `when` in the statement | a write with a `when` |
|
|
520
|
+
| `invariants: true` | judges the Entity's invariants | a write of an Entity that has any |
|
|
521
|
+
| `increments: true` | adds `increments` in the statement | a write with an increment |
|
|
522
|
+
| `assignments: true` | computes `assignments` in the statement | a write with a computed assignment |
|
|
523
|
+
| `ledger: true` (with `recorded`) | records each update and insert under its `operation`, and answers a retry from the record | an increment or computed assignment with no `expect` |
|
|
524
|
+
| `requires: true` | holds the row to `requires` | `GuardServer.writer` over a rule reading another row, which throws where it is made without it |
|
|
525
|
+
| `refuses(write)` | names what only its store knows it cannot land (the Drizzle writer: a fractional amount for an integer column) | every write, asked once |
|
|
507
526
|
|
|
508
527
|
A writer with a `read` (the row as a principal may see it, under the read
|
|
509
528
|
rule its Source applies) answers through it: the patch is the written row as
|
|
@@ -515,34 +534,147 @@ it where the server would not list it. A writer may refuse with
|
|
|
515
534
|
rows they point at, so such a guard can tell a write that unlinks a hidden row
|
|
516
535
|
from one that changes nothing; `foldkit-remote-drizzle`'s `writer` has both.
|
|
517
536
|
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
537
|
+
### What an answer carries
|
|
538
|
+
|
|
539
|
+
A Source answers the rows it changed; the client says what it shows of them.
|
|
540
|
+
`Data.mutate` sends, with each request, what its active Surfaces read of each
|
|
541
|
+
entity, every field its optimistic layer shows, and the supplied members a
|
|
542
|
+
created or edited row foresees (`may`) (`shown`). After the Source runs, the handler reads, of each row the
|
|
543
|
+
outcome names (a patch, or a list insert), the shown fields the patch left out
|
|
544
|
+
and every shown relation, and answers that read beside the patch (`read`):
|
|
545
|
+
|
|
546
|
+
```text
|
|
547
|
+
outcome rows × client's shown fields − fields the patch carries -> read -> answer
|
|
548
|
+
```
|
|
549
|
+
|
|
550
|
+
So a declared write, which answers the columns it stored, also answers the
|
|
551
|
+
derived count, the `may` and the author's name the page reads of the row, and
|
|
552
|
+
the client releases its optimistic layer with nothing left to fetch. The read
|
|
553
|
+
is an ordinary one: the Sources' `read`, `authorize` and `filter` decide it, a
|
|
554
|
+
field the asker may not read comes back settled, and a row they cannot see is
|
|
555
|
+
left out of it, keeping what the patch gave.
|
|
556
|
+
|
|
557
|
+
A Source whose write the server cannot see (a row of a join table, a count it
|
|
558
|
+
keeps itself) names the row with no values, and the read answers all of it:
|
|
559
|
+
|
|
560
|
+
```ts
|
|
561
|
+
// Sketch, inside a mutation Source over a `Post` Entity: a like in a join table
|
|
562
|
+
// changes its post, so name the post and read nothing yourself.
|
|
563
|
+
return { output: { liked: true }, entities: [Remote.patch(Post, input.postId, {})] }
|
|
564
|
+
```
|
|
565
|
+
|
|
566
|
+
The read runs after the write commits, outside its transaction. If it fails,
|
|
567
|
+
it is reported as an `AnswerUnread` [diagnostic](#diagnostics) and the
|
|
568
|
+
mutation is answered without it: the write has
|
|
569
|
+
landed, and the client fetches what it lacks as it would have. A deleted row is
|
|
570
|
+
not read.
|
|
571
|
+
|
|
572
|
+
A request also names the lists the client judges the write moves (`lists`):
|
|
573
|
+
each the first page of a query, as the client's read entry would ask for it.
|
|
574
|
+
The handler admits them before the write runs, then reads each after it with
|
|
575
|
+
the query's own handler, so the page is what `FoldkitRemoteQuery` would answer,
|
|
576
|
+
`authorize` and `filter` included, and answers them beside the rows (`lists`):
|
|
577
|
+
|
|
578
|
+
```text
|
|
579
|
+
request lists -> admitted (before the write) -> read as queries (after it) -> answer.lists
|
|
580
|
+
```
|
|
581
|
+
|
|
582
|
+
A list is admitted when its query is one the server serves, its window is a
|
|
583
|
+
first page (`first`, no `after`), its `select` names the query's Entity within
|
|
584
|
+
a read's page bound, and the rows of every list admitted so far stay within
|
|
585
|
+
`maxIdsPerEntity` per Entity. One that is not, or whose read fails (reported
|
|
586
|
+
as `AnswerUnread`), is left out; the write runs either way, and the client
|
|
587
|
+
fetches that list as it would have. The wire refuses more than
|
|
588
|
+
`MAX_ANSWER_LISTS` lists in one request.
|
|
589
|
+
|
|
590
|
+
A declared write (`RemoteServer.write`) also reads each row its row points at
|
|
591
|
+
through a `one` relation, before and after the write, through the writer's
|
|
592
|
+
`linked`, where that link can change one of the row's derived members: a
|
|
593
|
+
`Derived.count` or `Derived.exists` over that relation, or any supplied member
|
|
594
|
+
(`Derived.make`), which may read anything. Inserting a `Like` reads what the
|
|
595
|
+
page shows of its post, the new `likeCount` included
|
|
596
|
+
([#233](https://github.com/doeixd/foldkit-plus/issues/233)), and not its user,
|
|
597
|
+
whose members no like changes. A member declared after `Entity.relate` counts:
|
|
598
|
+
the Entity has one set of members, whichever descriptor declared them
|
|
599
|
+
([#332](https://github.com/doeixd/foldkit-plus/issues/332)). A row's derived
|
|
600
|
+
members change only with the rows pointing at it, so no app names them. These rows are read, never sent as patches of their own: one the
|
|
601
|
+
asker may not see is not answered at all. Live subscribers hear the outcome's
|
|
602
|
+
own patches, not the read, which is one asker's view.
|
|
521
603
|
|
|
522
604
|
## Live data
|
|
523
605
|
|
|
524
|
-
|
|
606
|
+
A live subscription is one stream per Entity, from that Entity's live Source.
|
|
607
|
+
There are three ways to produce one:
|
|
608
|
+
|
|
609
|
+
- write a live Source directly, below;
|
|
610
|
+
- over Drizzle, `foldkit-remote-drizzle`'s `pollLive`, a live Source that
|
|
611
|
+
re-reads the subscribed rows and lists from inside the subscriber's own
|
|
612
|
+
request, which is what Workers need;
|
|
613
|
+
- in a long-lived process, a `liveHub` that re-reads what each write changed.
|
|
525
614
|
|
|
526
615
|
### Write a live Source directly
|
|
527
616
|
|
|
528
617
|
```ts
|
|
618
|
+
// `projectEvents` is your own stream of `LiveChange`s.
|
|
529
619
|
const ProjectLive = RemoteServer.live(Project, {
|
|
530
|
-
subscribe: ({ requirements, after, principal }) =>
|
|
620
|
+
subscribe: ({ requirements, queries, after, principal }) =>
|
|
531
621
|
projectEvents({
|
|
532
622
|
requirements,
|
|
623
|
+
queries,
|
|
533
624
|
after,
|
|
534
625
|
principal,
|
|
535
626
|
}),
|
|
536
627
|
})
|
|
537
628
|
```
|
|
538
629
|
|
|
539
|
-
`after` is the client's resume cursor. Events at or before it are duplicates
|
|
630
|
+
`after` is the client's resume cursor. Events at or before it are duplicates,
|
|
631
|
+
and the stream's cursors count on from it: its first event is `after + 1`, or
|
|
632
|
+
the client takes the skipped cursors for a gap and restarts the stream.
|
|
540
633
|
The stream carries Remote `LiveChange`s: entity patches/deletes and connection
|
|
541
634
|
insert/remove/invalidate events.
|
|
542
635
|
|
|
636
|
+
`queries` are the lists of this Entity the subscriber reads live
|
|
637
|
+
(`liveQuery(Data, …)`), each a `LiveQuery` the handler has already
|
|
638
|
+
admitted and resolved: `identity` (the connection as the client keys it, for
|
|
639
|
+
the connection events), `select` (what the read draws of each row), and
|
|
640
|
+
`edges`, the registered query run as the subscriber with the page's window.
|
|
641
|
+
The handler refuses, with `RemoteLiveRefused` and before any live Source is
|
|
642
|
+
asked, a list of a query it does not register, an input that does not
|
|
643
|
+
decode, one with no `select` or no `first`, one whose `select` is of another
|
|
644
|
+
Entity than its query lists (a `QuerySource` names that Entity: `RemoteServer.query`
|
|
645
|
+
reads it from the descriptor's connection), and one whose `first`, added to
|
|
646
|
+
the ids of its Entity the subscription names, passes `maxIdsPerEntity`. A
|
|
647
|
+
subscription watches at most 32 lists (`MAX_LIVE_QUERIES`), refused at decode.
|
|
648
|
+
|
|
543
649
|
If an Entity has no live Source, it contributes no stream. That is not an error:
|
|
544
650
|
the client planner can fall back to refetching it.
|
|
545
651
|
|
|
652
|
+
A live Source that reads rows to send them must read them as a read would, or
|
|
653
|
+
it sends what the read handlers withhold. `RemoteServer.readAs` is that read:
|
|
654
|
+
only the asked fields the Source declares and its `authorize` allows, each
|
|
655
|
+
record through its `filter`, and no other field.
|
|
656
|
+
|
|
657
|
+
```ts
|
|
658
|
+
const asReader = RemoteServer.readAs(ProjectSource, {
|
|
659
|
+
ids: ['p1'],
|
|
660
|
+
fields: ['name', 'privateNotes'],
|
|
661
|
+
principal: { isAdmin: false },
|
|
662
|
+
})
|
|
663
|
+
// An Effect that succeeds with Option.some([{ id: 'p1', values: { name: 'Apollo' } }]),
|
|
664
|
+
// or Option.none() when the principal may read none of the fields asked.
|
|
665
|
+
```
|
|
666
|
+
|
|
667
|
+
`RemoteServer.allowedFields(ProjectSource, principal, fields)` says which of
|
|
668
|
+
`fields` that read would read, without reading: a Source reading several rows
|
|
669
|
+
together, each asked for fields of its own, reads them in one read and still
|
|
670
|
+
tells nothing of a row whose fields the principal may read none of.
|
|
671
|
+
|
|
672
|
+
A live Source that sends only what it reads through one Source names it as
|
|
673
|
+
`reads`, so a startup check can trust it as far as it trusts that Source:
|
|
674
|
+
`GuardServer.validate` accepts a live Source over a guarded Entity only when
|
|
675
|
+
it `reads` the guarded Source it checked. `foldkit-remote-drizzle`'s `pollLive`
|
|
676
|
+
reads through `readAs` and sets `reads`.
|
|
677
|
+
|
|
546
678
|
### Let a `liveHub` re-read changed fields
|
|
547
679
|
|
|
548
680
|
A hub fans **what changed** out to live subscribers. Give it to the handlers,
|
|
@@ -551,6 +683,7 @@ fields it carries, each deletion as a deletion. A mutation Source names nothing
|
|
|
551
683
|
twice.
|
|
552
684
|
|
|
553
685
|
```ts
|
|
686
|
+
// Inside an Effect.gen: building a hub is an Effect.
|
|
554
687
|
const entitySources = [ProjectSource]
|
|
555
688
|
const hub = yield* RemoteServer.liveHub(entitySources)
|
|
556
689
|
|
|
@@ -559,13 +692,14 @@ const handlers = RemoteServer.handlers(Server, principal, {
|
|
|
559
692
|
})
|
|
560
693
|
|
|
561
694
|
// Only for a write that is not a mutation: a database trigger consumer, a job.
|
|
562
|
-
yield* hub.changed(Project.ref(
|
|
563
|
-
yield* hub.deleted(Project.ref(
|
|
695
|
+
yield* hub.changed(Project.ref('p1'), ['name'])
|
|
696
|
+
yield* hub.deleted(Project.ref('p1'))
|
|
564
697
|
```
|
|
565
698
|
|
|
566
699
|
A mutation's publish runs after its Source returned, so after a write that
|
|
567
|
-
commits as it goes. A failed publish is
|
|
568
|
-
|
|
700
|
+
commits as it goes. A failed publish is reported as a `PublishFailed`
|
|
701
|
+
[diagnostic](#diagnostics) and the mutation still answers: its write has
|
|
702
|
+
happened, and a failed answer would be retried.
|
|
569
703
|
|
|
570
704
|
The hub remembers each subscriber's requirements and principal. `changed`:
|
|
571
705
|
|
|
@@ -586,7 +720,11 @@ Subscribers that selected none of the changed fields do no work, and
|
|
|
586
720
|
subscribers with one principal share one re-read. One principal means the same
|
|
587
721
|
value, unless the hub is given a `key`: then two requests whose principals
|
|
588
722
|
have one key, each with a principal object of its own, share it, read as the
|
|
589
|
-
first of them. A key must therefore name everything the Sources decide by
|
|
723
|
+
first of them. A key must therefore name everything the Sources decide by,
|
|
724
|
+
the reader itself included when a Source answers a viewer-relative member (a
|
|
725
|
+
`Derived.exists`, whose value is each reader's own; `foldkit-guard`'s
|
|
726
|
+
`Policy.keyOf` names every field of the principal). A key by role, as here,
|
|
727
|
+
fits Sources that answer only by role:
|
|
590
728
|
|
|
591
729
|
```ts
|
|
592
730
|
const hub = yield* RemoteServer.liveHub(entitySources, {
|
|
@@ -622,14 +760,16 @@ const SharedProjectSource = RemoteServer.entity<Principal>(Project, {
|
|
|
622
760
|
re-read.
|
|
623
761
|
- `foldkit-remote-drizzle`'s `source` and `RemoteServer.memory` take it too,
|
|
624
762
|
and `foldkit-guard`'s `GuardServer.validate` refuses a shared field a Read
|
|
625
|
-
rule could tell readers apart by.
|
|
763
|
+
rule could tell readers apart by. `source` refuses a `Derived.exists` as
|
|
764
|
+
shared: it is each reader's own.
|
|
626
765
|
|
|
627
766
|
A hub is an in-memory fan-out, so whatever calls `changed` must be able to wake
|
|
628
767
|
the subscriber's fiber. In a worker it cannot: one request cannot wake another's
|
|
629
768
|
stream, so a hub fed from a second request delivers nothing and tears the first
|
|
630
|
-
stream down
|
|
631
|
-
|
|
632
|
-
|
|
769
|
+
stream down: the open response belongs to the request that opened it, and the
|
|
770
|
+
Workers runtime cancels it when another request wakes it. On Workers, poll the
|
|
771
|
+
shared store from inside the subscriber's own request instead, as `pollLive`
|
|
772
|
+
does. A hub is right for a long-lived server process that owns both sides.
|
|
633
773
|
|
|
634
774
|
A hand-written live Source and a hub number their events independently. Use one
|
|
635
775
|
or the other for a given subscription path rather than mixing cursor domains.
|
|
@@ -688,7 +828,7 @@ A complete server definition is just the collection of Sources:
|
|
|
688
828
|
|
|
689
829
|
```ts
|
|
690
830
|
const Server = RemoteServer.make({
|
|
691
|
-
entities: [ProjectSource
|
|
831
|
+
entities: [ProjectSource],
|
|
692
832
|
queries: [ProjectsByOwnerSource],
|
|
693
833
|
mutations: [RenameProjectSource],
|
|
694
834
|
live: [ProjectLive],
|
|
@@ -700,7 +840,7 @@ Source names at startup:
|
|
|
700
840
|
|
|
701
841
|
```ts
|
|
702
842
|
const Data = Remote.define({
|
|
703
|
-
entities: [Project
|
|
843
|
+
entities: [Project],
|
|
704
844
|
queries: [ProjectsByOwner],
|
|
705
845
|
mutations: [RenameProject],
|
|
706
846
|
})
|
|
@@ -711,6 +851,30 @@ RemoteServer.validate(Data, Server)
|
|
|
711
851
|
That catches an Entity, Query, or Mutation Source whose name is not declared by
|
|
712
852
|
the shared domain instead of letting it silently answer nothing at runtime.
|
|
713
853
|
|
|
854
|
+
`viewer` says who asks, as a row, and is the server's one answer to it:
|
|
855
|
+
`RemoteServer.make({ ..., viewer: principal => Option<{ entity, id }> })`. The
|
|
856
|
+
server hands it to every Source it mounts, with each read, query and live
|
|
857
|
+
subscription (`EntitySourceContext.viewer`), and to every write. A Source
|
|
858
|
+
answering a member per reader declares it (`perViewer`, as a `Derived.exists`
|
|
859
|
+
does), and a server with no `viewer` refuses that Source where it is made,
|
|
860
|
+
naming it. A query body's `Expr.viewer` and `Expr.now` read this viewer and the
|
|
861
|
+
server's Effect `Clock` (`exprContext`).
|
|
862
|
+
|
|
863
|
+
The viewer is also whom every answer says it is for. A read's, a list's and a
|
|
864
|
+
mutation's result carry `principal`: the viewer's key (`'User:ada'`), or
|
|
865
|
+
`null` for a visitor. The client treats it as opaque, stamps each durable
|
|
866
|
+
write it queues with it, and sends it back with every send of that write. The
|
|
867
|
+
handlers compare it with whom they answer as before the mutation's Source
|
|
868
|
+
runs: another person is refused with `RemotePrincipalChanged` (a 409 over
|
|
869
|
+
JSON), a visitor with `Unauthenticated`, and nothing runs, a ledger's replay
|
|
870
|
+
included, so a write resent after the cookie changed hands is never run, or
|
|
871
|
+
answered from its record, as someone else. A write that names `null` (made
|
|
872
|
+
with no one signed in) runs only for a visitor; asked by someone signed in it
|
|
873
|
+
is refused with `RemotePrincipalChanged`, unrun. A write that names no one
|
|
874
|
+
(made before any answer said who) runs as whoever asks.
|
|
875
|
+
A server with no `viewer` keeps no keys: its answers carry no `principal`, and
|
|
876
|
+
it refuses a write that names one, which it cannot check.
|
|
877
|
+
|
|
714
878
|
Then compile it into handlers, once per principal, or once for every request
|
|
715
879
|
with a Context key as the principal (see Authentication vs authorization):
|
|
716
880
|
|
|
@@ -763,18 +927,37 @@ The handler applies bounded, protocol-level safeguards before or around Sources:
|
|
|
763
927
|
|
|
764
928
|
- a read batch may name at most `maxIdsPerEntity` distinct ids for one Entity
|
|
765
929
|
(default `1000`); oversized client batches fail rather than loading unbounded
|
|
766
|
-
rows
|
|
930
|
+
rows. Remote's client cuts its batches to the same default, and to the
|
|
931
|
+
number given in `Remote.clientLayer(…, { maxIdsPerEntity })`;
|
|
932
|
+
- a request body may be at most `maxBodyBytes` (default 1 MiB) where bytes are
|
|
933
|
+
read: `serveFetch`'s option, and `bodyLimit` in front of an `RpcServer`
|
|
934
|
+
route. A larger one is a 413, `{ error, tooLarge: { limit } }`, refused by
|
|
935
|
+
its `content-length` before anything else, or cancelled the moment the bytes
|
|
936
|
+
read pass the limit, and never decoded;
|
|
767
937
|
- nested resolution is bounded by `maxDepth` (default `8`);
|
|
768
938
|
- the wire decoder also rejects a selection deeper than
|
|
769
939
|
`MAX_RELATION_DEPTH` (`8`) or more than `MAX_FIELDS_PER_REQUEST` (`256`)
|
|
770
940
|
fields for one Entity;
|
|
941
|
+
- a collection relation read with no window is the Source's to bound:
|
|
942
|
+
`foldkit-remote-drizzle`'s `source` reads at most `maxCollection` children
|
|
943
|
+
of one row (default 100) and refuses a read that finds more, rather than
|
|
944
|
+
answering a list cut short;
|
|
771
945
|
- returned field names are copied with `Object.hasOwn` into null-prototype
|
|
772
946
|
objects, so names such as `__proto__` or `toString` cannot reach prototypes;
|
|
773
947
|
- Source errors are remapped to protocol error types without echoing application
|
|
774
948
|
internals.
|
|
775
949
|
|
|
776
|
-
A
|
|
777
|
-
Source
|
|
950
|
+
A live subscription is held to the same bounds, checked once by the handler
|
|
951
|
+
before any live Source or the hub sees it: more than `maxIdsPerEntity` ids of
|
|
952
|
+
one Entity (the `first` of each live list of it counted with them), or more
|
|
953
|
+
pages of one relation than a read may ask, fails the stream with
|
|
954
|
+
`RemoteLiveRefused` and nothing is read; more than `MAX_LIVE_QUERIES` (32) live
|
|
955
|
+
lists fails the wire decoder before that. That matters most for a polling
|
|
956
|
+
Source such as `pollLive`, which re-reads every subscribed row each tick. A
|
|
957
|
+
refusal is not truncation: the client does not reconnect it, and
|
|
958
|
+
`liveStatus(Data, …)` reads `Refused`. A hand-written live Source can rely on what
|
|
959
|
+
it is given having passed, and is responsible for any further bounds its
|
|
960
|
+
backend needs.
|
|
778
961
|
|
|
779
962
|
## A backend held in memory
|
|
780
963
|
|
|
@@ -788,10 +971,9 @@ is refused where the server is built.
|
|
|
788
971
|
|
|
789
972
|
```ts
|
|
790
973
|
const backend = RemoteServer.memory({
|
|
791
|
-
domain: Data, //
|
|
974
|
+
domain: Data, // the definition from Remote.define, or a domain from Remote.make
|
|
792
975
|
rows: {
|
|
793
|
-
|
|
794
|
-
Project: [{ id: 'p1', name: 'Apollo', status: 'active', owner: 'User:u1' }],
|
|
976
|
+
Project: [{ id: 'p1', name: 'Apollo', privateNotes: 'Internal' }],
|
|
795
977
|
},
|
|
796
978
|
// Optional: each mutation writes through the store, and the next read sees it.
|
|
797
979
|
mutations: store => [
|
|
@@ -942,16 +1124,57 @@ const route = async (request: Request): Promise<Response> => {
|
|
|
942
1124
|
call, of whatever kind, with `_tag: 'Unauthenticated'`.
|
|
943
1125
|
- **403** with `{ error, forbidden: { reason? } }`: who is asking may not do
|
|
944
1126
|
this (`RemoteServer.forbid`).
|
|
1127
|
+
- **409** with `{ error, refusal }`: a declared insert's id is already a
|
|
1128
|
+
row's, refused as `Refusal.taken`.
|
|
1129
|
+
- **409** with `{ error, principalChanged: {} }`: the write names someone
|
|
1130
|
+
other than who asks (`RemotePrincipalChanged`). Nothing ran. The client
|
|
1131
|
+
fails it with `_tag: 'PrincipalChanged'`, and the outbox keeps it waiting
|
|
1132
|
+
for them.
|
|
945
1133
|
- **422** with `{ error, refusal }`: the mutation refused what was asked, in
|
|
946
1134
|
its own `Refusal`.
|
|
947
1135
|
- **500** with `{ error }`: the handler failed, and the message is its own;
|
|
948
1136
|
or something on this side broke, and the message is `Internal error`,
|
|
949
|
-
nothing more.
|
|
1137
|
+
nothing more. The cause is reported as a `ServerDefect`
|
|
1138
|
+
[diagnostic](#diagnostics), by default to the log, so a Worker's log
|
|
1139
|
+
(`wrangler tail`) shows what broke.
|
|
1140
|
+
|
|
1141
|
+
It never answers 408, 429, 502, 503 or 504. Remote's client reads a body
|
|
1142
|
+
under one of those, or one that is not JSON, as no answer at all
|
|
1143
|
+
(`Unreachable`): a proxy, gateway or rate limiter in front that answers one
|
|
1144
|
+
leaves the client unsure whether the write ran, and a durable write is sent
|
|
1145
|
+
again (see [A write sent again](#a-write-sent-again-operation)).
|
|
950
1146
|
|
|
951
1147
|
It binds no principal: pass the `handlers` for the request's own,
|
|
952
1148
|
established by your authentication, as everywhere else. It carries no live
|
|
953
1149
|
data.
|
|
954
1150
|
|
|
1151
|
+
For an endpoint that serves `RemoteRpc` through Effect's own `RpcServer`,
|
|
1152
|
+
`bodyLimit(maxBytes)` is the same limit as HTTP middleware (Effect's
|
|
1153
|
+
`MaxBodySize` fails the RPC body read as a defect, a 500):
|
|
1154
|
+
|
|
1155
|
+
```ts
|
|
1156
|
+
import { Layer } from 'effect'
|
|
1157
|
+
import { HttpRouter } from 'effect/http'
|
|
1158
|
+
import { RpcSerialization, RpcServer } from 'effect/rpc'
|
|
1159
|
+
import { RemoteRpc } from 'foldkit-remote'
|
|
1160
|
+
import { RemoteServer, bodyLimit } from 'foldkit-remote-server'
|
|
1161
|
+
|
|
1162
|
+
// `server` is your RemoteServer.make; answered as an anonymous principal here.
|
|
1163
|
+
const RpcRoutes = RpcServer.layer(RemoteRpc).pipe(
|
|
1164
|
+
Layer.provide(RemoteRpc.toLayer(RemoteServer.handlers(server, 'anonymous'))),
|
|
1165
|
+
Layer.provide(RpcServer.layerProtocolHttp({ path: '/rpc' })),
|
|
1166
|
+
Layer.provide(RpcSerialization.layerJson),
|
|
1167
|
+
Layer.provide(HttpRouter.middleware(bodyLimit(64 * 1024)).layer),
|
|
1168
|
+
)
|
|
1169
|
+
```
|
|
1170
|
+
|
|
1171
|
+
The client reads that 413 as the call's own error, and a 401 or 403 from
|
|
1172
|
+
session middleware in front of the route as `Unauthenticated` or `Forbidden`,
|
|
1173
|
+
only over `Remote.rpcProtocolHttp(url)` in place of
|
|
1174
|
+
`RpcClient.layerProtocolHttp({ url })`, which reads the refusal as RPC frames
|
|
1175
|
+
and loses its status: a durable write would then read as unreachable and be
|
|
1176
|
+
sent again for good.
|
|
1177
|
+
|
|
955
1178
|
## Over fetch (Workers)
|
|
956
1179
|
|
|
957
1180
|
`serveFetch` from `foldkit-remote-server/fetch` is that route as a value: a
|
|
@@ -964,6 +1187,7 @@ what `layer` provides (a session store, an auth service):
|
|
|
964
1187
|
```ts
|
|
965
1188
|
import { serveFetch } from 'foldkit-remote-server/fetch'
|
|
966
1189
|
|
|
1190
|
+
// `server` is your RemoteServer.make; `databaseLayer` and `drizzle` provide what its Sources need.
|
|
967
1191
|
export default {
|
|
968
1192
|
fetch: serveFetch({
|
|
969
1193
|
server,
|
|
@@ -974,8 +1198,18 @@ export default {
|
|
|
974
1198
|
}
|
|
975
1199
|
```
|
|
976
1200
|
|
|
977
|
-
Only `POST`s to `path` (default `/remote`) are answered; anything else is a
|
|
978
|
-
|
|
1201
|
+
Only `POST`s to `path` (default `/remote`) are answered; anything else is a
|
|
1202
|
+
404. A body larger than `maxBodyBytes` (default 1 MiB) is a 413 with
|
|
1203
|
+
`{ error, tooLarge: { limit } }`: one whose `content-length` says so before
|
|
1204
|
+
the layer is built or the principal resolved, any other once the bytes read
|
|
1205
|
+
pass the limit, its stream cancelled there. Give the client the same number
|
|
1206
|
+
(`Remote.clientLayer(Remote.http('/remote'), { maxBodyBytes })`) and it cuts its
|
|
1207
|
+
reads to fit; `Remote.http` reads a 413 as the call's own error, so a durable
|
|
1208
|
+
write is not resent. A body that is not UTF-8 JSON, or not a request, is a 400
|
|
1209
|
+
that reaches no handler; a handler's failure a 500 with its message. Every response, refusals
|
|
1210
|
+
and errors included, says `cache-control: no-store` unless `headers` gives a
|
|
1211
|
+
`cache-control` of its own: each answer is one principal's rows (and `may`), so
|
|
1212
|
+
no shared cache may keep one.
|
|
979
1213
|
|
|
980
1214
|
A resolver refuses the caller by failing with
|
|
981
1215
|
`RemoteServer.unauthenticated(reason?)`: a 401 whose body is
|
|
@@ -1003,7 +1237,7 @@ A body that opens live (`{ operation: 'live', payload }`) is answered with
|
|
|
1003
1237
|
the stream as `text/event-stream`: one `data:` frame per `LiveChange`, then
|
|
1004
1238
|
a terminal `event: error` frame carrying the failure's message when the
|
|
1005
1239
|
stream fails rather than ends. A payload no live stream speaks is a 400 that
|
|
1006
|
-
subscribes to nothing. `
|
|
1240
|
+
subscribes to nothing. `httpWithLive` (`foldkit-remote/live`) is the other end; a client that
|
|
1007
1241
|
disconnects interrupts the subscription, as closing the RPC stream would.
|
|
1008
1242
|
|
|
1009
1243
|
The stream moves on its own even when nothing changes: a `: ping` comment opens
|
|
@@ -1015,27 +1249,164 @@ the events it serves, so a stream with nothing to serve still ends.
|
|
|
1015
1249
|
calls it must be able to wake the subscriber's fiber: in a worker, one request
|
|
1016
1250
|
cannot wake another's stream, so a hub fed from a second request delivers
|
|
1017
1251
|
nothing and ends the first stream. Poll the shared store from inside the
|
|
1018
|
-
subscriber's own request instead
|
|
1019
|
-
|
|
1252
|
+
subscriber's own request instead: `foldkit-remote-drizzle`'s `pollLive` does,
|
|
1253
|
+
with a trigger-kept row log (`rowChangeLog`, `rowLog`) so a quiet tick reads
|
|
1254
|
+
no rows. A hub is right for a long-lived process that owns both sides.
|
|
1255
|
+
|
|
1256
|
+
### A page's reads, in the same process: `pageReader`
|
|
1257
|
+
|
|
1258
|
+
A Worker that renders pages reads what each page shows before rendering it
|
|
1259
|
+
(`Data.satisfy`), as the reader who asked. `pageReader` is that reader, made
|
|
1260
|
+
from the same config `serveFetch` takes: the request's `RemoteClient` as a
|
|
1261
|
+
Layer, answered by the server's own handlers with no HTTP in between. The
|
|
1262
|
+
server, its `layer` and its limits are the ones `/remote` answers with.
|
|
1263
|
+
|
|
1264
|
+
```ts
|
|
1265
|
+
import { pageReader, serveFetch } from 'foldkit-remote-server/fetch'
|
|
1266
|
+
|
|
1267
|
+
const remote = { server, resolvePrincipal, layer: (env: Env) => databaseLayer(drizzle(env.DB)) }
|
|
1268
|
+
const served = serveFetch(remote)
|
|
1269
|
+
const reader = pageReader({ ...remote, resolvePrincipal: resolvePage })
|
|
1270
|
+
|
|
1271
|
+
export default {
|
|
1272
|
+
fetch: (request: Request, env: Env) =>
|
|
1273
|
+
new URL(request.url).pathname === '/remote'
|
|
1274
|
+
? served(request, env)
|
|
1275
|
+
: pages.fetch(PageContext.attach(request, { reader: reader(request, env) })),
|
|
1276
|
+
}
|
|
1277
|
+
```
|
|
1278
|
+
|
|
1279
|
+
`pages` is the fetch handler Foldkit's build emits, and `PageContext` an
|
|
1280
|
+
`SSR.requestContext` that carries the reader to `renderPage`
|
|
1281
|
+
([`foldkit-ssr`](../ssr/README.md#what-the-host-hands-the-page-ssrrequestcontext)).
|
|
1282
|
+
|
|
1283
|
+
The resolver is the page's own: a page `GET` is a navigation, which carries
|
|
1284
|
+
no header a script adds, so a resolver that asks for one (Yielded's CSRF
|
|
1285
|
+
header) refuses it. With `foldkit-auth`, give
|
|
1286
|
+
`AuthServer.resolver({ …, requests: 'navigation' })`. When the reader is
|
|
1287
|
+
provided, the principal is resolved and `layer` built, and `layer` closes
|
|
1288
|
+
when that Effect ends, so provide it to the pre-read itself
|
|
1289
|
+
(`Data.satisfy(…).pipe(Effect.provide(reader))`). A refusal fails it with
|
|
1290
|
+
`Unauthenticated`, as a 401 would.
|
|
1291
|
+
|
|
1292
|
+
The reader only reads. A mutation fails with `RemoteMutationError` and a live
|
|
1293
|
+
open with `RemoteLiveError`: another site can start a navigation, so the
|
|
1294
|
+
principal it resolves must never write, and a render keeps no stream.
|
|
1295
|
+
|
|
1296
|
+
## Diagnostics
|
|
1297
|
+
|
|
1298
|
+
A server answers some failures without telling the caller why. Each is a
|
|
1299
|
+
typed diagnostic, reported through `Diagnostics.Reporter` (`foldkit-surface`'s
|
|
1300
|
+
channel, re-exported by `foldkit-remote`), which by default is Effect's log:
|
|
1301
|
+
|
|
1302
|
+
| `_tag` | `level` | When |
|
|
1303
|
+
| --- | --- | --- |
|
|
1304
|
+
| `ServerDefect` | `error` | Something on this side broke (a layer, a resolver, a handler's defect) and the caller was answered `Internal error`; it carries the `cause`. |
|
|
1305
|
+
| `AnswerUnread` | `warning` | A mutation committed, but reading its answer failed: the client reads those rows again. |
|
|
1306
|
+
| `PublishFailed` | `error` | A mutation committed, but its live publish failed: live subscribers do not hear it. |
|
|
1307
|
+
| `ClockSkewed` | `warning` | A write's time was past `clockSkew` from the server's clock (a client clock that is off, or a durable write that waited), so the server wrote its own; it carries `sent`, `own` and `bound`. |
|
|
1308
|
+
|
|
1309
|
+
Provide another reporter as any service: `Layer.succeed(Diagnostics.Reporter,
|
|
1310
|
+
report)` in the layer the handlers run in. `serveFetch` takes one with the
|
|
1311
|
+
request beside it, used for everything that request runs, a broken layer
|
|
1312
|
+
included:
|
|
1313
|
+
|
|
1314
|
+
```ts
|
|
1315
|
+
serveFetch({
|
|
1316
|
+
server,
|
|
1317
|
+
resolvePrincipal,
|
|
1318
|
+
layer: (env: Env) => databaseLayer(env),
|
|
1319
|
+
diagnostics: (diagnostic, request) =>
|
|
1320
|
+
Effect.logError(`${request.method} ${request.url}: ${diagnostic.message}`),
|
|
1321
|
+
})
|
|
1322
|
+
```
|
|
1323
|
+
|
|
1324
|
+
In a test, `Diagnostics.collect()` gives a reporter and the array it fills.
|
|
1325
|
+
|
|
1326
|
+
## Reference semantics: `evaluate` and the conformance suite
|
|
1327
|
+
|
|
1328
|
+
### Running a query body over rows you already hold
|
|
1329
|
+
|
|
1330
|
+
A descriptor declared with
|
|
1331
|
+
[`Query.define`](../remote#queries-and-pagination) carries its meaning as a
|
|
1332
|
+
value (`body`), and `evaluate` runs a body directly:
|
|
1020
1333
|
|
|
1021
|
-
|
|
1334
|
+
```ts
|
|
1335
|
+
import { Entity, Expr, Order, Query, evaluate } from 'foldkit-entity'
|
|
1336
|
+
|
|
1337
|
+
const Post = Entity.define('Post', Schema.Struct({ id: Schema.String, slug: Schema.String }))
|
|
1338
|
+
const intro = Query.from(Post).pipe(
|
|
1339
|
+
Query.where(Expr.eq(Post.fields.slug, 'intro')),
|
|
1340
|
+
Query.orderBy(Order.asc(Post.fields.id)),
|
|
1341
|
+
)
|
|
1342
|
+
|
|
1343
|
+
evaluate(intro, {}, [{ id: 'p1', slug: 'intro' }, { id: 'p2', slug: 'outro' }])
|
|
1344
|
+
// [{ id: 'p1', slug: 'intro' }]: the matching rows, in the order the body asks for
|
|
1345
|
+
```
|
|
1346
|
+
|
|
1347
|
+
It lives in [`foldkit-entity`](../entity), beside the IR it interprets, because
|
|
1348
|
+
it is that IR's reference semantics rather than anything this package does —
|
|
1349
|
+
and because a client judging rows it already holds needs it without depending on
|
|
1350
|
+
a server package. This package re-exports it, so importing it from either place
|
|
1351
|
+
means the same thing.
|
|
1352
|
+
|
|
1353
|
+
It is pure — it reads the rows it is given and nothing else — and it is the
|
|
1354
|
+
reference the compiled interpreters are checked against. `foldkit-remote-drizzle`
|
|
1355
|
+
turns the same body into SQL; the test suite runs both over the same rows in a
|
|
1356
|
+
real SQLite and Postgres and requires the same ids in the same order. That is
|
|
1357
|
+
what makes a body source-neutral in fact rather than in principle.
|
|
1358
|
+
|
|
1359
|
+
**It follows SQL, not JavaScript.** The case that matters is null: `null = null`
|
|
1360
|
+
is *unknown* in SQL and matches no row, where JavaScript would call the two
|
|
1361
|
+
equal. A comparison keeps a row only when it is true, so a null on either side
|
|
1362
|
+
drops it. Where an ordering puts null is the term's to say
|
|
1363
|
+
(`Order.asc(field, { nulls: 'first' })`); unsaid, it is Postgres's (last
|
|
1364
|
+
ascending, first descending), which the SQL compiler writes out for SQLite too.
|
|
1365
|
+
|
|
1366
|
+
What it refuses rather than guesses, each where the query runs:
|
|
1367
|
+
|
|
1368
|
+
- **Ordering by values it has no order for**, such as a number in one row and
|
|
1369
|
+
text in another, or by a backend's locale collation, which only that backend
|
|
1370
|
+
has. Every term is checked over every matched row before anything is sorted,
|
|
1371
|
+
so the refusal is the same on every engine, whichever pair a sort would have
|
|
1372
|
+
compared first. One matched row, or none, has nothing to order.
|
|
1373
|
+
- **NaN**, which SQLite stores as null and Postgres orders after every number.
|
|
1374
|
+
- **Text holding a NUL character** in a comparison or a search, which Postgres
|
|
1375
|
+
text cannot hold and SQLite's `like` stops at.
|
|
1376
|
+
- **A term with no context.** A body reading `Expr.viewer` or `Expr.now` is
|
|
1377
|
+
refused when run without them (`ContextMissingError`), never read as null.
|
|
1022
1378
|
|
|
1023
|
-
|
|
1379
|
+
### Checking an interpreter against the semantics
|
|
1024
1380
|
|
|
1025
|
-
|
|
1026
|
-
|
|
1027
|
-
|
|
1028
|
-
|
|
1029
|
-
|
|
1030
|
-
|
|
1381
|
+
`evaluate` is the reference, and `cases` (in `foldkit-entity/conformance`) is
|
|
1382
|
+
what it is a reference *to*: the conformance suite, exported so an interpreter
|
|
1383
|
+
written elsewhere can be held to the same semantics. Here `run` is your
|
|
1384
|
+
interpreter:
|
|
1385
|
+
|
|
1386
|
+
```ts
|
|
1387
|
+
import { cases, rows } from 'foldkit-entity/conformance'
|
|
1388
|
+
|
|
1389
|
+
for (const { what, body, input, expected } of cases) {
|
|
1390
|
+
expect(run(body, input, rows).map(row => row.id), what).toEqual(expected)
|
|
1391
|
+
}
|
|
1392
|
+
```
|
|
1031
1393
|
|
|
1032
|
-
|
|
1033
|
-
|
|
1394
|
+
Every case is chosen to make interpreters **disagree**, which is the only kind
|
|
1395
|
+
that tests anything: mixed case, nulls on both sides of a comparison, `%` and
|
|
1396
|
+
`_` as literal text, the empty search, a predicate compared to a boolean either
|
|
1397
|
+
way round. That is not caution for its own sake — `contains` reached a released
|
|
1398
|
+
package meaning three different things because every value in the original
|
|
1399
|
+
fixture happened to be lowercase.
|
|
1400
|
+
|
|
1401
|
+
Both interpreters here run it: this package over rows in memory, and
|
|
1402
|
+
`foldkit-remote-drizzle` compiled to SQL against a real SQLite and Postgres.
|
|
1034
1403
|
|
|
1035
1404
|
## See also
|
|
1036
1405
|
|
|
1037
1406
|
- [Server-derived state](../../docs/remote.md) — the client/server mental model
|
|
1038
1407
|
and ownership rules.
|
|
1408
|
+
- [Errors and failures](../../docs/errors.md) — what a client is and is not
|
|
1409
|
+
told, beside the failures every other package owns.
|
|
1039
1410
|
- [`foldkit-remote`](../remote) — requirements, normalized client Model,
|
|
1040
1411
|
subscriptions, mutations, live reads, and retention.
|
|
1041
1412
|
- [`foldkit-remote-drizzle`](../remote-drizzle) — compile Entity selections and
|