foldkit-remote-server 0.19.0 → 0.21.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 +215 -11
- package/dist/fetch.d.mts +55 -4
- package/dist/fetch.d.mts.map +1 -1
- package/dist/fetch.mjs +259 -26
- package/dist/fetch.mjs.map +1 -1
- package/dist/{index-BnaRbvjr.d.mts → index-pMrHmWZt.d.mts} +116 -18
- package/dist/index-pMrHmWZt.d.mts.map +1 -0
- package/dist/index.d.mts +2 -2
- package/dist/index.mjs +1 -1
- package/dist/{src-ZV9pARkU.mjs → src-CHkHaItI.mjs} +313 -74
- package/dist/src-CHkHaItI.mjs.map +1 -0
- package/package.json +7 -7
- package/dist/index-BnaRbvjr.d.mts.map +0 -1
- package/dist/src-ZV9pARkU.mjs.map +0 -1
package/README.md
CHANGED
|
@@ -386,7 +386,13 @@ A refusal of who is asking, rather than of what they asked, is
|
|
|
386
386
|
`Effect.fail(RemoteServer.forbid('Only an admin may archive.'))`: sent as
|
|
387
387
|
`Forbidden` with the reason (a 403 over JSON), or with none when `forbid()` is
|
|
388
388
|
given none, so the refusal says nothing of why. It is the same for every
|
|
389
|
-
mutation, so it needs no `Refusal` declared.
|
|
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.
|
|
390
396
|
|
|
391
397
|
A Source may additionally return connection changes:
|
|
392
398
|
|
|
@@ -532,7 +538,8 @@ from one that changes nothing; `foldkit-remote-drizzle`'s `writer` has both.
|
|
|
532
538
|
|
|
533
539
|
A Source answers the rows it changed; the client says what it shows of them.
|
|
534
540
|
`Data.mutate` sends, with each request, what its active Surfaces read of each
|
|
535
|
-
entity
|
|
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
|
|
536
543
|
outcome names (a patch, or a list insert), the shown fields the patch left out
|
|
537
544
|
and every shown relation, and answers that read beside the patch (`read`):
|
|
538
545
|
|
|
@@ -562,6 +569,24 @@ mutation is answered without it: the write has
|
|
|
562
569
|
landed, and the client fetches what it lacks as it would have. A deleted row is
|
|
563
570
|
not read.
|
|
564
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
|
+
|
|
565
590
|
A declared write (`RemoteServer.write`) also reads each row its row points at
|
|
566
591
|
through a `one` relation, before and after the write, through the writer's
|
|
567
592
|
`linked`, where that link can change one of the row's derived members: a
|
|
@@ -609,7 +634,7 @@ The stream carries Remote `LiveChange`s: entity patches/deletes and connection
|
|
|
609
634
|
insert/remove/invalidate events.
|
|
610
635
|
|
|
611
636
|
`queries` are the lists of this Entity the subscriber reads live
|
|
612
|
-
(`Data
|
|
637
|
+
(`liveQuery(Data, …)`), each a `LiveQuery` the handler has already
|
|
613
638
|
admitted and resolved: `identity` (the connection as the client keys it, for
|
|
614
639
|
the connection events), `select` (what the read draws of each row), and
|
|
615
640
|
`edges`, the registered query run as the subscriber with the page's window.
|
|
@@ -835,6 +860,21 @@ does), and a server with no `viewer` refuses that Source where it is made,
|
|
|
835
860
|
naming it. A query body's `Expr.viewer` and `Expr.now` read this viewer and the
|
|
836
861
|
server's Effect `Clock` (`exprContext`).
|
|
837
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
|
+
|
|
838
878
|
Then compile it into handlers, once per principal, or once for every request
|
|
839
879
|
with a Context key as the principal (see Authentication vs authorization):
|
|
840
880
|
|
|
@@ -887,7 +927,13 @@ The handler applies bounded, protocol-level safeguards before or around Sources:
|
|
|
887
927
|
|
|
888
928
|
- a read batch may name at most `maxIdsPerEntity` distinct ids for one Entity
|
|
889
929
|
(default `1000`); oversized client batches fail rather than loading unbounded
|
|
890
|
-
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;
|
|
891
937
|
- nested resolution is bounded by `maxDepth` (default `8`);
|
|
892
938
|
- the wire decoder also rejects a selection deeper than
|
|
893
939
|
`MAX_RELATION_DEPTH` (`8`) or more than `MAX_FIELDS_PER_REQUEST` (`256`)
|
|
@@ -909,7 +955,7 @@ pages of one relation than a read may ask, fails the stream with
|
|
|
909
955
|
lists fails the wire decoder before that. That matters most for a polling
|
|
910
956
|
Source such as `pollLive`, which re-reads every subscribed row each tick. A
|
|
911
957
|
refusal is not truncation: the client does not reconnect it, and
|
|
912
|
-
`Data
|
|
958
|
+
`liveStatus(Data, …)` reads `Refused`. A hand-written live Source can rely on what
|
|
913
959
|
it is given having passed, and is responsible for any further bounds its
|
|
914
960
|
backend needs.
|
|
915
961
|
|
|
@@ -1080,6 +1126,10 @@ const route = async (request: Request): Promise<Response> => {
|
|
|
1080
1126
|
this (`RemoteServer.forbid`).
|
|
1081
1127
|
- **409** with `{ error, refusal }`: a declared insert's id is already a
|
|
1082
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.
|
|
1083
1133
|
- **422** with `{ error, refusal }`: the mutation refused what was asked, in
|
|
1084
1134
|
its own `Refusal`.
|
|
1085
1135
|
- **500** with `{ error }`: the handler failed, and the message is its own;
|
|
@@ -1098,6 +1148,33 @@ It binds no principal: pass the `handlers` for the request's own,
|
|
|
1098
1148
|
established by your authentication, as everywhere else. It carries no live
|
|
1099
1149
|
data.
|
|
1100
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
|
+
|
|
1101
1178
|
## Over fetch (Workers)
|
|
1102
1179
|
|
|
1103
1180
|
`serveFetch` from `foldkit-remote-server/fetch` is that route as a value: a
|
|
@@ -1122,11 +1199,18 @@ export default {
|
|
|
1122
1199
|
```
|
|
1123
1200
|
|
|
1124
1201
|
Only `POST`s to `path` (default `/remote`) are answered; anything else is a
|
|
1125
|
-
404. A body
|
|
1126
|
-
|
|
1127
|
-
|
|
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: private, no-store` unless `headers` gives a
|
|
1128
1211
|
`cache-control` of its own: each answer is one principal's rows (and `may`), so
|
|
1129
|
-
no shared cache may keep one.
|
|
1212
|
+
no shared cache may keep one. The one exception is a read the server proves
|
|
1213
|
+
public, with `cache` (below).
|
|
1130
1214
|
|
|
1131
1215
|
A resolver refuses the caller by failing with
|
|
1132
1216
|
`RemoteServer.unauthenticated(reason?)`: a 401 whose body is
|
|
@@ -1154,7 +1238,7 @@ A body that opens live (`{ operation: 'live', payload }`) is answered with
|
|
|
1154
1238
|
the stream as `text/event-stream`: one `data:` frame per `LiveChange`, then
|
|
1155
1239
|
a terminal `event: error` frame carrying the failure's message when the
|
|
1156
1240
|
stream fails rather than ends. A payload no live stream speaks is a 400 that
|
|
1157
|
-
subscribes to nothing. `
|
|
1241
|
+
subscribes to nothing. `httpWithLive` (`foldkit-remote/live`) is the other end; a client that
|
|
1158
1242
|
disconnects interrupts the subscription, as closing the RPC stream would.
|
|
1159
1243
|
|
|
1160
1244
|
The stream moves on its own even when nothing changes: a `: ping` comment opens
|
|
@@ -1210,6 +1294,126 @@ The reader only reads. A mutation fails with `RemoteMutationError` and a live
|
|
|
1210
1294
|
open with `RemoteLiveError`: another site can start a navigation, so the
|
|
1211
1295
|
principal it resolves must never write, and a render keeps no stream.
|
|
1212
1296
|
|
|
1297
|
+
With `cache`, the reader answers each read it proves public as the visitor,
|
|
1298
|
+
and notes every read for the render (`PageReads`): public with its
|
|
1299
|
+
freshness and the rows it holds, or private. `foldkit-ssr`'s `SSR.entry`
|
|
1300
|
+
keeps a page only when every read it made was public.
|
|
1301
|
+
|
|
1302
|
+
### Keeping public reads: `cache`
|
|
1303
|
+
|
|
1304
|
+
A read every visitor gets the same answer to costs the same work every
|
|
1305
|
+
time it is asked. With `cache`, `serveFetch` keeps such reads and answers
|
|
1306
|
+
them again from a store, without asking a Source:
|
|
1307
|
+
|
|
1308
|
+
```text
|
|
1309
|
+
a read -> public? (no rule about who asks, freshness declared)
|
|
1310
|
+
-> yes: answered as the visitor, kept by its body for maxAge
|
|
1311
|
+
-> no: answered as who asks, cache-control: private, no-store
|
|
1312
|
+
a write -> purges every kept read holding a row it names, and every list of that row's entity
|
|
1313
|
+
```
|
|
1314
|
+
|
|
1315
|
+
The domain declares how long a read stays fresh; it never says who may
|
|
1316
|
+
share it. An Entity says it with `EdgeCache.of`, a Query with `cache`:
|
|
1317
|
+
|
|
1318
|
+
```ts standalone
|
|
1319
|
+
import { Effect, Layer, Schema } from 'effect'
|
|
1320
|
+
import { Entity } from 'foldkit-entity'
|
|
1321
|
+
import { CacheStore, EdgeCache, Query, REMOTE_PROTOCOL_VERSION } from 'foldkit-remote'
|
|
1322
|
+
import { RemoteServer } from 'foldkit-remote-server'
|
|
1323
|
+
import { checkCache, serveFetch } from 'foldkit-remote-server/fetch'
|
|
1324
|
+
|
|
1325
|
+
const Price = Entity.define(
|
|
1326
|
+
'Price',
|
|
1327
|
+
Schema.Struct({ id: Schema.String, amount: Schema.Number }),
|
|
1328
|
+
).pipe(Entity.annotate(EdgeCache.of({ maxAge: '60 seconds' })))
|
|
1329
|
+
const Cheap = Query.make('Cheap', { Input: {}, Result: Price, cache: { maxAge: '30 seconds' } })
|
|
1330
|
+
|
|
1331
|
+
const server = RemoteServer.make({
|
|
1332
|
+
entities: [
|
|
1333
|
+
RemoteServer.entity(Price, {
|
|
1334
|
+
read: ({ ids }) => Effect.succeed(ids.map(id => ({ id, values: { id, amount: 12 } }))),
|
|
1335
|
+
}),
|
|
1336
|
+
],
|
|
1337
|
+
})
|
|
1338
|
+
|
|
1339
|
+
const config = {
|
|
1340
|
+
server,
|
|
1341
|
+
resolvePrincipal: (request: Request) =>
|
|
1342
|
+
Effect.succeed({ userId: request.headers.get('x-user') ?? undefined }),
|
|
1343
|
+
layer: () => Layer.empty,
|
|
1344
|
+
}
|
|
1345
|
+
export const fetch = serveFetch({
|
|
1346
|
+
...config,
|
|
1347
|
+
cache: { store: CacheStore.memory(), visitor: { userId: undefined } },
|
|
1348
|
+
})
|
|
1349
|
+
```
|
|
1350
|
+
|
|
1351
|
+
Whether a read is public is the server's to prove, from the Sources it
|
|
1352
|
+
passes through: a read or query is public only when no Source on its way
|
|
1353
|
+
(its Entity's, each relation's it reaches, a query's own and its `select`'s)
|
|
1354
|
+
has an `authorize`, a `filter`, a `visible` rule or a member answered per
|
|
1355
|
+
viewer (`Derived.exists`), and each declares a freshness. Those rules are
|
|
1356
|
+
functions of the principal the server cannot read, so a Source with one is
|
|
1357
|
+
private even where its rule happens to read only the row: a guarded Entity
|
|
1358
|
+
(`foldkit-guard`), a Drizzle binding with `visible`, a `memory` backend with
|
|
1359
|
+
`readable`. Nothing is cached that the server could not prove.
|
|
1360
|
+
|
|
1361
|
+
A public read is answered as `visitor`, whoever asks: one answer, right for
|
|
1362
|
+
everyone, and never someone's own, even from a Source whose `read` looks at
|
|
1363
|
+
the principal. `visitor` must be no one: `serveFetch` refuses one the
|
|
1364
|
+
server's `viewer` names a row for. The answer names nobody it was for (no
|
|
1365
|
+
`principal`), says `cache-control: public, max-age=…` for the shortest
|
|
1366
|
+
freshness it reaches, and is kept by the SHA-256 of its body under
|
|
1367
|
+
`/__foldkit/cache/remote/` on the request's origin. A refusal or a failure
|
|
1368
|
+
is not kept. Everything else (a write, a live stream, a read that is not
|
|
1369
|
+
public) says `private, no-store`.
|
|
1370
|
+
|
|
1371
|
+
A write answered here purges what its answer names: each row it wrote,
|
|
1372
|
+
deleted, moved in a list or read back (`shown`, carried `lists`), and every
|
|
1373
|
+
list of each of their entities, which a changed row can join or leave. A
|
|
1374
|
+
write that is not answered by this `serveFetch` (another server, a job, a
|
|
1375
|
+
database trigger) purges nothing: what it changed is served as it was kept
|
|
1376
|
+
until `maxAge`.
|
|
1377
|
+
|
|
1378
|
+
`CacheStore.memory({ limit })` keeps answers in the process, for Node, a dev
|
|
1379
|
+
server and tests (1,000 by default, the oldest dropped first).
|
|
1380
|
+
`CacheStore.workers(caches.default)` keeps them in the Workers Cache API;
|
|
1381
|
+
which answers a tag names is known to the isolate that kept them, so a
|
|
1382
|
+
write purges what this isolate kept, and another isolate's or data centre's
|
|
1383
|
+
copy stays until its `maxAge`. Give `pageReader` the same config, and pages
|
|
1384
|
+
read through it are judged the same way (`foldkit-ssr`'s `cache`).
|
|
1385
|
+
|
|
1386
|
+
The checker answers each public read as two principals. `cache.check`
|
|
1387
|
+
answers it as who asks too, and where the two differ reports
|
|
1388
|
+
`CachedReadDiffers` and gives the asker their own: a development mode.
|
|
1389
|
+
`checkCache(config, requests, env)` is the same, for a test: it serves each
|
|
1390
|
+
request twice with `check` and a store in memory, and rejects a difference,
|
|
1391
|
+
or a set of requests with no public read, which would check nothing:
|
|
1392
|
+
|
|
1393
|
+
```ts
|
|
1394
|
+
const asking = (user?: string) => () =>
|
|
1395
|
+
new Request('https://shop.test/remote', {
|
|
1396
|
+
method: 'POST',
|
|
1397
|
+
headers: user === undefined ? {} : { 'x-user': user },
|
|
1398
|
+
body: JSON.stringify({
|
|
1399
|
+
operation: 'read',
|
|
1400
|
+
payload: {
|
|
1401
|
+
version: REMOTE_PROTOCOL_VERSION,
|
|
1402
|
+
requests: [{ entity: 'Price', id: 'a', fields: ['amount'] }],
|
|
1403
|
+
},
|
|
1404
|
+
}),
|
|
1405
|
+
})
|
|
1406
|
+
|
|
1407
|
+
export const checked = checkCache(
|
|
1408
|
+
{ ...config, cache: { visitor: { userId: undefined } } },
|
|
1409
|
+
[asking(), asking('u1')],
|
|
1410
|
+
undefined,
|
|
1411
|
+
)
|
|
1412
|
+
```
|
|
1413
|
+
|
|
1414
|
+
`Cheap` is a Query a server registers with `RemoteServer.query`; its answer
|
|
1415
|
+
is kept for 30 seconds, the shorter of its own and `Price`'s.
|
|
1416
|
+
|
|
1213
1417
|
## Diagnostics
|
|
1214
1418
|
|
|
1215
1419
|
A server answers some failures without telling the caller why. Each is a
|
|
@@ -1248,7 +1452,7 @@ A descriptor declared with
|
|
|
1248
1452
|
[`Query.define`](../remote#queries-and-pagination) carries its meaning as a
|
|
1249
1453
|
value (`body`), and `evaluate` runs a body directly:
|
|
1250
1454
|
|
|
1251
|
-
```ts
|
|
1455
|
+
```ts standalone
|
|
1252
1456
|
import { Entity, Expr, Order, Query, evaluate } from 'foldkit-entity'
|
|
1253
1457
|
|
|
1254
1458
|
const Post = Entity.define('Post', Schema.Struct({ id: Schema.String, slug: Schema.String }))
|
package/dist/fetch.d.mts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { M as ServerDefinition, u as LiveHub } from "./index-pMrHmWZt.mjs";
|
|
2
2
|
import { Duration, Effect, Layer } from "effect";
|
|
3
|
-
import { Diagnostic, RemoteClient, RemoteUnauthenticated } from "foldkit-remote";
|
|
3
|
+
import { CacheStore, Diagnostic, RemoteClient, RemoteUnauthenticated } from "foldkit-remote";
|
|
4
4
|
/** What `serveFetch` needs of the host runtime, per request. */
|
|
5
5
|
export interface FetchConfig<P, R, Env, RP = never> {
|
|
6
6
|
/** The server definition, as `RemoteServer.make` built it. */
|
|
@@ -57,6 +57,35 @@ export interface FetchConfig<P, R, Env, RP = never> {
|
|
|
57
57
|
readonly maxIdsPerEntity?: number | undefined;
|
|
58
58
|
/** A nested selection may not reach further than this many levels; default 8. */
|
|
59
59
|
readonly maxDepth?: number | undefined;
|
|
60
|
+
/**
|
|
61
|
+
* A request body may not be larger than this many bytes; default 1 MiB. A
|
|
62
|
+
* larger one is a 413 with Remote's `tooLarge` answer, refused before it is
|
|
63
|
+
* decoded: by its `content-length` before the principal is resolved, or
|
|
64
|
+
* once the bytes read pass the limit. Give the client the same number
|
|
65
|
+
* (`Remote.clientLayer(…, { maxBodyBytes })`), so it cuts its reads to fit.
|
|
66
|
+
*/
|
|
67
|
+
readonly maxBodyBytes?: number | undefined;
|
|
68
|
+
/**
|
|
69
|
+
* Keeps public reads in `store` (#428). A read or query is public where
|
|
70
|
+
* none of the sources it passes through has a rule about who asks
|
|
71
|
+
* (`authorize`, `filter`, `visible`, a member per viewer) and each declares
|
|
72
|
+
* how long it stays fresh (`EdgeCache.of` on its Entity, `cache` on its
|
|
73
|
+
* Query). A public read is answered as `visitor`, whoever asks, so one
|
|
74
|
+
* answer is right for everyone, and kept for the shortest `maxAge` it
|
|
75
|
+
* reaches; it says `cache-control: public, max-age=…`. Every other answer
|
|
76
|
+
* says `private, no-store`. A write answered here purges the kept reads
|
|
77
|
+
* holding a row it names, and every list of that row's entity.
|
|
78
|
+
*
|
|
79
|
+
* `visitor` is the principal of someone not signed in: refused when the
|
|
80
|
+
* server's `viewer` names a row for it. With `check`, for development and
|
|
81
|
+
* tests, each public read is also answered as who asks, and a difference
|
|
82
|
+
* is reported (`CachedReadDiffers`) and answered with the asker's own.
|
|
83
|
+
*/
|
|
84
|
+
readonly cache?: {
|
|
85
|
+
readonly store: CacheStore;
|
|
86
|
+
readonly visitor: P;
|
|
87
|
+
readonly check?: boolean | undefined;
|
|
88
|
+
} | undefined;
|
|
60
89
|
}
|
|
61
90
|
/**
|
|
62
91
|
* Answers Remote `POST`s with `Response`s: what a Worker's `fetch` hands to
|
|
@@ -82,8 +111,25 @@ export interface FetchConfig<P, R, Env, RP = never> {
|
|
|
82
111
|
* ```
|
|
83
112
|
*/
|
|
84
113
|
export declare const serveFetch: <P, R, Env, RP = never>(config: FetchConfig<P, R, Env, RP>) => ((request: Request, env: Env) => Promise<Response>);
|
|
85
|
-
/**
|
|
86
|
-
|
|
114
|
+
/**
|
|
115
|
+
* The cache's checker, for a test: serves each request twice through
|
|
116
|
+
* `serveFetch` with `cache.check` and a store in memory, so every public read
|
|
117
|
+
* is answered both as the visitor (kept, then from the store) and as whoever
|
|
118
|
+
* the request resolves to. Rejects naming each read whose answers differ, and
|
|
119
|
+
* when no read was public, which would check nothing. Give requests from at
|
|
120
|
+
* least two principals, a visitor's and someone's; each is a function, since
|
|
121
|
+
* a body is read once.
|
|
122
|
+
*/
|
|
123
|
+
export declare const checkCache: <P, R, Env, RP = never>(config: Omit<FetchConfig<P, R, Env, RP>, 'cache' | 'diagnostics'> & {
|
|
124
|
+
readonly cache: {
|
|
125
|
+
readonly visitor: P;
|
|
126
|
+
};
|
|
127
|
+
}, requests: ReadonlyArray<() => Request>, env: Env) => Promise<void>;
|
|
128
|
+
/**
|
|
129
|
+
* What `pageReader` reads of a `serveFetch` config: the server, its Sources'
|
|
130
|
+
* layer, its limits, and the cache's `visitor`.
|
|
131
|
+
*/
|
|
132
|
+
export type PageReaderConfig<P, R, Env, RP = never> = Pick<FetchConfig<P, R, Env, RP>, 'server' | 'resolvePrincipal' | 'layer' | 'maxIdsPerEntity' | 'maxDepth' | 'cache'>;
|
|
87
133
|
/**
|
|
88
134
|
* The reader a page render reads through, in the same process: the request's
|
|
89
135
|
* `RemoteClient`, answered by the server's own handlers with no HTTP between
|
|
@@ -97,6 +143,11 @@ export type PageReaderConfig<P, R, Env, RP = never> = Pick<FetchConfig<P, R, Env
|
|
|
97
143
|
* refusal fails that Effect with `Unauthenticated`, as a 401 would. It only
|
|
98
144
|
* reads: a mutation fails with `RemoteMutationError` and a live open with
|
|
99
145
|
* `RemoteLiveError`, since a navigation can be started from another site.
|
|
146
|
+
*
|
|
147
|
+
* Each read is noted for a render `foldkit-ssr` may cache (`PageReads`):
|
|
148
|
+
* with `cache`, one proved public as `serveFetch` proves it is answered as
|
|
149
|
+
* `cache.visitor` and noted public; every other read, and every read without
|
|
150
|
+
* `cache`, is noted private, which keeps the page from being cached.
|
|
100
151
|
*/
|
|
101
152
|
export declare const pageReader: <P, R, Env, RP = never>(config: PageReaderConfig<P, R, Env, RP>) => (request: Request, env: Env) => Layer.Layer<RemoteClient, RemoteUnauthenticated>;
|
|
102
153
|
//# sourceMappingURL=fetch.d.mts.map
|
package/dist/fetch.d.mts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"fetch.d.mts","names":[],"sources":["../src/fetch.ts"],"mappings":";;;;
|
|
1
|
+
{"version":3,"file":"fetch.d.mts","names":[],"sources":["../src/fetch.ts"],"mappings":";;;;iBAgEiB,YAAY,GAAG,GAAG,KAAK;;WAE7B,QAAQ,iBAAiB,GAAG;;;;;;WAM5B,mBACP,SAAS,SACT,KAAK,QACF,OAAO,OAAO,GAAG,uBAAuB;;;;;;WAMpC,QAAQ,KAAK,QAAQ,MAAM,MAAM,IAAI;;WAErC;;;;;;;WAOA,YAAY,WAAW,MAAM,SAAS;;WAEtC,OAAO,QAAQ,GAAG;;;;;;;;;;;;WAYlB;aAEM,OAAO,SAAS;aAChB,QAAQ,WAAW;;;WAIzB,gBAAgB,SAAS;;;;;;;;WAQzB,gBACH,YAAY,YAAY,SAAS,YAAY,OAAO;;WAGjD;;WAEA;;;;;;;;WAQA;;;;;;;;;;;;;;;;;WAiBA;aAEM,OAAO;aACP,SAAS;aACT;;;;;;;;;;;;;;;;;;;;;;;;;;qBAgOJ,aAAc,GAAG,GAAG,KAAK,YAAU,QACtC,YAAY,GAAG,GAAG,KAAK,UAC5B,SAAS,SAAS,KAAK,QAAQ,QAAQ;;;;;;;;;;qBA2M/B,aAAoB,GAAG,GAAG,KAAK,YAAU,QAC5C,KAAK,YAAY,GAAG,GAAG,KAAK;WACzB;aAAkB,SAAS;;GACrC,UACS,oBAAoB,UAAQ,KACjC,QACJ;;;;;YAyBS,iBAAiB,GAAG,GAAG,KAAK,cAAc,KACpD,YAAY,GAAG,GAAG,KAAK;;;;;;;;;;;;;;;;;;;;qBAuBZ,aAAc,GAAG,GAAG,KAAK,YAAU,QAAU,iBAAiB,GAAG,GAAG,KAAK,SAAG,SAMtE,SAAO,KAAO,QAAM,MAAM,MAAM,cAAc"}
|