foldkit-remote-server 0.20.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 CHANGED
@@ -1207,9 +1207,10 @@ pass the limit, its stream cancelled there. Give the client the same number
1207
1207
  reads to fit; `Remote.http` reads a 413 as the call's own error, so a durable
1208
1208
  write is not resent. A body that is not UTF-8 JSON, or not a request, is a 400
1209
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
1210
+ and errors included, says `cache-control: private, no-store` unless `headers` gives a
1211
1211
  `cache-control` of its own: each answer is one principal's rows (and `may`), so
1212
- 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).
1213
1214
 
1214
1215
  A resolver refuses the caller by failing with
1215
1216
  `RemoteServer.unauthenticated(reason?)`: a 401 whose body is
@@ -1293,6 +1294,126 @@ The reader only reads. A mutation fails with `RemoteMutationError` and a live
1293
1294
  open with `RemoteLiveError`: another site can start a navigation, so the
1294
1295
  principal it resolves must never write, and a render keeps no stream.
1295
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
+
1296
1417
  ## Diagnostics
1297
1418
 
1298
1419
  A server answers some failures without telling the caller why. Each is a
@@ -1331,7 +1452,7 @@ A descriptor declared with
1331
1452
  [`Query.define`](../remote#queries-and-pagination) carries its meaning as a
1332
1453
  value (`body`), and `evaluate` runs a body directly:
1333
1454
 
1334
- ```ts
1455
+ ```ts standalone
1335
1456
  import { Entity, Expr, Order, Query, evaluate } from 'foldkit-entity'
1336
1457
 
1337
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 { j as ServerDefinition, l as LiveHub } from "./index-B85UhEfk.mjs";
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. */
@@ -65,6 +65,27 @@ export interface FetchConfig<P, R, Env, RP = never> {
65
65
  * (`Remote.clientLayer(…, { maxBodyBytes })`), so it cuts its reads to fit.
66
66
  */
67
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;
68
89
  }
69
90
  /**
70
91
  * Answers Remote `POST`s with `Response`s: what a Worker's `fetch` hands to
@@ -90,8 +111,25 @@ export interface FetchConfig<P, R, Env, RP = never> {
90
111
  * ```
91
112
  */
92
113
  export declare const serveFetch: <P, R, Env, RP = never>(config: FetchConfig<P, R, Env, RP>) => ((request: Request, env: Env) => Promise<Response>);
93
- /** What `pageReader` reads of a `serveFetch` config: the server, its Sources' layer and its limits. */
94
- export type PageReaderConfig<P, R, Env, RP = never> = Pick<FetchConfig<P, R, Env, RP>, 'server' | 'resolvePrincipal' | 'layer' | 'maxIdsPerEntity' | 'maxDepth'>;
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'>;
95
133
  /**
96
134
  * The reader a page render reads through, in the same process: the request's
97
135
  * `RemoteClient`, answered by the server's own handlers with no HTTP between
@@ -105,6 +143,11 @@ export type PageReaderConfig<P, R, Env, RP = never> = Pick<FetchConfig<P, R, Env
105
143
  * refusal fails that Effect with `Unauthenticated`, as a 401 would. It only
106
144
  * reads: a mutation fails with `RemoteMutationError` and a live open with
107
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.
108
151
  */
109
152
  export declare const pageReader: <P, R, Env, RP = never>(config: PageReaderConfig<P, R, Env, RP>) => (request: Request, env: Env) => Layer.Layer<RemoteClient, RemoteUnauthenticated>;
110
153
  //# sourceMappingURL=fetch.d.mts.map
@@ -1 +1 @@
1
- {"version":3,"file":"fetch.d.mts","names":[],"sources":["../src/fetch.ts"],"mappings":";;;;iBA6CiB,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;;;;;;;;;;;;;;;;;;;;;;;;;qBAsJE,aAAc,GAAG,GAAG,KAAK,YAAU,QACtC,YAAY,GAAG,GAAG,KAAK,UAC5B,SAAS,SAAS,KAAK,QAAQ,QAAQ;;YA6HhC,iBAAiB,GAAG,GAAG,KAAK,cAAc,KACpD,YAAY,GAAG,GAAG,KAAK;;;;;;;;;;;;;;;qBAkBZ,aACV,GAAG,GAAG,KAAK,YAAU,QAAU,iBAAiB,GAAG,GAAG,KAAK,SAAG,SACrD,SAAO,KAAO,QAAM,MAAM,MAAM,cAAc"}
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"}
package/dist/fetch.mjs CHANGED
@@ -1,6 +1,112 @@
1
- import { d as declaresTooLarge, f as readJson, i as RemoteServer, p as tooLargeAnswer, v as unauthenticatedAnswer, y as serverDefect } from "./src-D8azLxgd.mjs";
2
- import { Cause, Deferred, Duration, Effect, Exit, Layer, Result, Schedule, Schema, Scope, Stream } from "effect";
3
- import { DEFAULT_MAX_BODY_BYTES, Diagnostics, LiveRequirement, Remote, RemoteLiveError, RemoteMutationError } from "foldkit-remote";
1
+ import { b as serverDefect, d as declaresTooLarge, f as readJson, i as RemoteServer, p as tooLargeAnswer, v as unauthenticatedAnswer, y as cachedReadDiffers } from "./src-CHkHaItI.mjs";
2
+ import { Cause, Deferred, Duration, Effect, Exit, Layer, Option, Result, Schedule, Schema, Scope, Stream } from "effect";
3
+ import { CacheStore, CachedRead, DEFAULT_MAX_BODY_BYTES, Diagnostics, LiveRequirement, MutationResult, PageReads, QueryRequest, QueryResult, ReadBatch, ReadBatchResult, Remote, RemoteJsonRequest, RemoteLiveError, RemoteMutationError, listTag, maxAgeSeconds, rowTag, shorterPolicy, stableStringify } from "foldkit-remote";
4
+ // src/edgeCache.ts
5
+ /**
6
+ * Which reads a server may share between whoever asks, and the tags a store
7
+ * keeps them under (#428).
8
+ *
9
+ * A read is public only where the server can prove nothing about it depends
10
+ * on who asks: every source it passes through has no `authorize`, no
11
+ * `filter`, no `visible` rule (a guard's, a binding's, `memory`'s
12
+ * `readable`) and no member answered per viewer, and every one declares how
13
+ * long it stays fresh. Those rules are functions of the principal this
14
+ * module cannot read, so it does not try: a source with one is private,
15
+ * even where its rule happens to read only the row. A public read is then
16
+ * answered as the visitor, whoever asks, so even a source's own `read` that
17
+ * looks at the principal gives everyone one answer, never someone's own.
18
+ */
19
+ /** A source's freshness, where nothing it runs is a rule about who asks. */
20
+ const sourcePolicy = (source) => source === void 0 || source.authorize !== void 0 || source.filter !== void 0 || source.visible !== void 0 || (source.perViewer ?? []).length > 0 ? Option.none() : Option.fromUndefinedOr(source.cache);
21
+ /** Two policies' shorter, none when either is none. */
22
+ const both = (a, b) => Option.flatMap(a, (left) => Option.map(b, (right) => shorterPolicy(left, right)));
23
+ /** A slice's policy: its entity's, and every relation's it reaches. */
24
+ const slicePolicy = (server, slice) => Object.values(slice.relations ?? {}).reduce((policy, relation) => both(policy, slicePolicy(server, relation)), sourcePolicy(server.entities.get(slice.entity)));
25
+ /** A read batch's policy: none for an empty one, which keeps nothing worth a key. */
26
+ const readPolicy = (server, batch) => batch.requests.length === 0 ? Option.none() : batch.requests.map((request) => slicePolicy(server, request)).reduce(both);
27
+ /** A query's policy: its own, its rows' and what its `select` reaches. */
28
+ const queryPolicy = (server, request) => {
29
+ const source = server.queries.get(request.query);
30
+ if (source === void 0 || source.visible !== void 0) return Option.none();
31
+ const own = both(Option.fromUndefinedOr(source.cache), sourcePolicy(server.entities.get(source.entity)));
32
+ return request.select === void 0 ? own : both(own, slicePolicy(server, request.select));
33
+ };
34
+ const rowTags = (rows) => rows.map((row) => rowTag(row.entity, row.id));
35
+ /** What a read's answer holds: each row asked for, found or not, and each it reached. */
36
+ const readTags = (batch, result) => [.../* @__PURE__ */ new Set([
37
+ ...rowTags(batch.requests),
38
+ ...rowTags(result.entities),
39
+ ...rowTags(result.settled)
40
+ ])];
41
+ /** What a query's answer holds: every list of its entity, and each row on the page. */
42
+ const queryTags = (server, request, result) => [.../* @__PURE__ */ new Set([
43
+ ...Option.toArray(Option.map(Option.fromUndefinedOr(server.queries.get(request.query)), (source) => listTag(source.entity))),
44
+ ...rowTags(result.edges),
45
+ ...rowTags(result.entities ?? [])
46
+ ])];
47
+ const decodeMutationResult = Schema.decodeUnknownOption(MutationResult);
48
+ /**
49
+ * What a write's answer names, as tags to purge: each row it wrote, deleted,
50
+ * moved in a list or read back, and every list of each of their entities,
51
+ * which a changed row can join or leave. A write naming nothing purges nothing.
52
+ */
53
+ const writeTags = (result) => Option.match(decodeMutationResult(result), {
54
+ onNone: () => [],
55
+ onSome: (answer) => {
56
+ const rows = [
57
+ ...answer.entities,
58
+ ...answer.deleted ?? [],
59
+ ...(answer.connections ?? []).map((change) => change.edge),
60
+ ...answer.read?.result.entities ?? [],
61
+ ...(answer.lists ?? []).flatMap((list) => [...list.result.edges, ...list.result.entities ?? []])
62
+ ];
63
+ return [.../* @__PURE__ */ new Set([...rowTags(rows), ...rows.map((row) => listTag(row.entity))])];
64
+ }
65
+ });
66
+ /** An answer as anyone may be given it: without whom it was for. */
67
+ const unaddressed = (answer) => {
68
+ const { principal: _, ...rest } = answer;
69
+ return rest;
70
+ };
71
+ const hex = (bytes) => [...new Uint8Array(bytes)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
72
+ /**
73
+ * The key a request's answer is kept under: the SHA-256 of `text` (the
74
+ * request as stable JSON), under the request's own origin, since the Workers
75
+ * Cache API keys by URL.
76
+ */
77
+ const cacheKey = (url, kind, text) => Effect.promise(() => crypto.subtle.digest("SHA-256", new TextEncoder().encode(text))).pipe(Effect.map((digest) => `${new URL(url).origin}/__foldkit/cache/${kind}/${hex(digest)}`));
78
+ /**
79
+ * Handlers that answer every read and query proved public as `visitor`, and
80
+ * note each read in the render's `PageReads`: public with its policy and
81
+ * tags, or private. Without a visitor every read is private, and so is one
82
+ * that fails, since a page drawn without its read is no page to keep.
83
+ */
84
+ const notingHandlers = (server, own, visitor) => {
85
+ const note = (read) => Effect.flatMap(Effect.service(PageReads), (noted) => Effect.sync(() => Option.map(noted, (add) => add(read))));
86
+ return {
87
+ ...own,
88
+ FoldkitRemoteRead: (batch) => Option.match(Option.flatMap(visitor, (handlers) => Option.map(readPolicy(server, batch), (policy) => ({
89
+ handlers,
90
+ policy
91
+ }))), {
92
+ onNone: () => Effect.ensuring(own.FoldkitRemoteRead(batch), note(CachedRead.Private())),
93
+ onSome: ({ handlers, policy }) => Effect.flatMap(handlers.FoldkitRemoteRead(batch), (result) => Effect.as(note(CachedRead.Public({
94
+ policy,
95
+ tags: readTags(batch, result)
96
+ })), unaddressed(result))).pipe(Effect.onError(() => note(CachedRead.Private())))
97
+ }),
98
+ FoldkitRemoteQuery: (request) => Option.match(Option.flatMap(visitor, (handlers) => Option.map(queryPolicy(server, request), (policy) => ({
99
+ handlers,
100
+ policy
101
+ }))), {
102
+ onNone: () => Effect.ensuring(own.FoldkitRemoteQuery(request), note(CachedRead.Private())),
103
+ onSome: ({ handlers, policy }) => Effect.flatMap(handlers.FoldkitRemoteQuery(request), (result) => Effect.as(note(CachedRead.Public({
104
+ policy,
105
+ tags: queryTags(server, request, result)
106
+ })), unaddressed(result))).pipe(Effect.onError(() => note(CachedRead.Private())))
107
+ })
108
+ };
109
+ };
4
110
  // src/fetch.ts
5
111
  /**
6
112
  * `foldkit-remote-server/fetch`: `RemoteServer` over the Fetch API, for
@@ -15,6 +121,41 @@ import { DEFAULT_MAX_BODY_BYTES, Diagnostics, LiveRequirement, Remote, RemoteLiv
15
121
  * binding, a session), and the Sources' requirements are provided per
16
122
  * request from the environment (a D1 binding, a connection string).
17
123
  */
124
+ const decodeRequest = Schema.decodeUnknownOption(RemoteJsonRequest);
125
+ const decodeBatch = Schema.decodeUnknownOption(ReadBatch);
126
+ const decodeQuery = Schema.decodeUnknownOption(QueryRequest);
127
+ const decodeReadResult = Schema.decodeUnknownOption(ReadBatchResult);
128
+ const decodeQueryResult = Schema.decodeUnknownOption(QueryResult);
129
+ /** `body`, when it is a read or query every source of which is public. */
130
+ const shareableOf = (server, body) => Option.flatMap(decodeRequest(body), ({ operation, payload }) => ({
131
+ read: () => Option.flatMap(decodeBatch(payload), (batch) => Option.map(readPolicy(server, batch), (policy) => ({
132
+ policy,
133
+ tagsOf: (result) => Option.match(decodeReadResult(result), {
134
+ onNone: () => [],
135
+ onSome: (read) => readTags(batch, read)
136
+ })
137
+ }))),
138
+ query: () => Option.flatMap(decodeQuery(payload), (request) => Option.map(queryPolicy(server, request), (policy) => ({
139
+ policy,
140
+ tagsOf: (result) => Option.match(decodeQueryResult(result), {
141
+ onNone: () => [],
142
+ onSome: (page) => queryTags(server, request, page)
143
+ })
144
+ }))),
145
+ mutate: () => Option.none()
146
+ })[operation]());
147
+ /** An answer as anyone may be given it: its result without whom it was for. */
148
+ const unaddressedAnswer = (answer) => {
149
+ if (!("result" in answer) || typeof answer.result !== "object" || answer.result === null) return answer;
150
+ const { principal: _, ...result } = answer.result;
151
+ return { result };
152
+ };
153
+ /** Whether `body` is a write: what it names, a cache purges. */
154
+ const isWrite = (body) => Option.exists(decodeRequest(body), (request) => request.operation === "mutate");
155
+ /** A visitor the server's `viewer` names a row for is someone: their reads are their own. */
156
+ const refuseSomeone = (server, cache) => {
157
+ if (cache !== void 0 && server.viewer !== void 0 && Option.isSome(server.viewer(cache.visitor))) throw new Error("foldkit-remote-server: cache.visitor must be no one, but the server viewer names a row for it");
158
+ };
18
159
  /** A live open over fetch: the requirements and the cursor it resumes after. */
19
160
  const LiveFetchRequest = Schema.Struct({
20
161
  operation: Schema.Literal("live"),
@@ -103,6 +244,7 @@ const liveResponse = (handlers, payload, heartbeat, checked, release, headers) =
103
244
  */
104
245
  const serveFetch = (config) => {
105
246
  const path = config.path ?? "/remote";
247
+ refuseSomeone(config.server, config.cache);
106
248
  const maxBodyBytes = config.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
107
249
  const heartbeat = config.liveHeartbeat ?? DEFAULT_HEARTBEAT;
108
250
  if (config.revalidate !== void 0 && !Duration.isGreaterThan(Duration.fromInputUnsafe(config.revalidate.every), Duration.zero)) throw new Error("serveFetch: revalidate.every must be longer than zero");
@@ -117,6 +259,48 @@ const serveFetch = (config) => {
117
259
  if (revalidate === void 0) return Stream.empty;
118
260
  return Stream.fromSchedule(Schedule.spaced(revalidate.every)).pipe(Stream.mapEffect(() => config.resolvePrincipal(request, env)), Stream.mapEffect((now) => revalidate.key === void 0 || revalidate.key(opened) === revalidate.key(now) ? Effect.void : Effect.fail(new RemoteLiveError({ message: "Who is asking changed: open the stream again" }))), Stream.drain);
119
261
  };
262
+ /**
263
+ * A public read: the visitor's answer, from the store or answered and kept.
264
+ * Under `check`, also the asker's own, which is given instead where they differ.
265
+ */
266
+ const answerShared = (request, body, cache, shareable, own, headers) => Effect.gen(function* () {
267
+ const asked = stableStringify(body);
268
+ const key = yield* cacheKey(request.url, "remote", asked);
269
+ const kept = yield* cache.store.match(key);
270
+ let text;
271
+ if (Option.isSome(kept)) text = kept.value;
272
+ else {
273
+ const visitor = RemoteServer.handlers(config.server, cache.visitor, {
274
+ maxIdsPerEntity: config.maxIdsPerEntity,
275
+ maxDepth: config.maxDepth
276
+ });
277
+ const answered = yield* RemoteServer.answer(visitor, body);
278
+ if (answered.status !== 200) return Response.json(answered.body, {
279
+ status: answered.status,
280
+ headers
281
+ });
282
+ text = JSON.stringify(unaddressedAnswer(answered.body));
283
+ yield* cache.store.put(key, text, {
284
+ maxAge: shareable.policy.maxAge,
285
+ tags: shareable.tagsOf("result" in answered.body ? answered.body.result : {})
286
+ });
287
+ }
288
+ if (cache.check === true) {
289
+ const mine = yield* RemoteServer.answer(own, body);
290
+ if (stableStringify(unaddressedAnswer(mine.body)) !== stableStringify(JSON.parse(text))) {
291
+ yield* Diagnostics.report(cachedReadDiffers(asked));
292
+ return Response.json(mine.body, {
293
+ status: mine.status,
294
+ headers
295
+ });
296
+ }
297
+ }
298
+ return new Response(text, { headers: {
299
+ "content-type": "application/json",
300
+ "cache-control": `public, max-age=${maxAgeSeconds(shareable.policy)}`,
301
+ ...headers
302
+ } });
303
+ });
120
304
  /** `live` is whether the response streams, and so owns `scope` until it ends. */
121
305
  const respond = (request, env, scope) => Effect.gen(function* () {
122
306
  const principal = yield* config.resolvePrincipal(request, env);
@@ -144,7 +328,14 @@ const serveFetch = (config) => {
144
328
  live: response.status === 200
145
329
  };
146
330
  }
331
+ const { cache } = config;
332
+ const shareable = cache === void 0 ? Option.none() : shareableOf(config.server, body.success);
333
+ if (cache !== void 0 && Option.isSome(shareable)) return {
334
+ response: yield* answerShared(request, body.success, cache, shareable.value, handlers, headers),
335
+ live: false
336
+ };
147
337
  const answered = yield* RemoteServer.answer(handlers, body.success);
338
+ if (cache !== void 0 && answered.status === 200 && isWrite(body.success)) yield* cache.store.purge(writeTags("result" in answered.body ? answered.body.result : {}));
148
339
  return {
149
340
  response: Response.json(answered.body, {
150
341
  status: answered.status,
@@ -172,11 +363,38 @@ const serveFetch = (config) => {
172
363
  };
173
364
  return async (request, env) => {
174
365
  const response = await served(request, env);
175
- if (!response.headers.has("cache-control")) response.headers.set("cache-control", "no-store");
366
+ if (!response.headers.has("cache-control")) response.headers.set("cache-control", "private, no-store");
176
367
  return response;
177
368
  };
178
369
  };
179
370
  /**
371
+ * The cache's checker, for a test: serves each request twice through
372
+ * `serveFetch` with `cache.check` and a store in memory, so every public read
373
+ * is answered both as the visitor (kept, then from the store) and as whoever
374
+ * the request resolves to. Rejects naming each read whose answers differ, and
375
+ * when no read was public, which would check nothing. Give requests from at
376
+ * least two principals, a visitor's and someone's; each is a function, since
377
+ * a body is read once.
378
+ */
379
+ const checkCache = async (config, requests, env) => {
380
+ const store = CacheStore.memory();
381
+ const differs = [];
382
+ const serve = serveFetch({
383
+ ...config,
384
+ cache: {
385
+ ...config.cache,
386
+ store,
387
+ check: true
388
+ },
389
+ diagnostics: (diagnostic) => Effect.sync(() => {
390
+ if (diagnostic._tag === "CachedReadDiffers") differs.push(diagnostic.message);
391
+ })
392
+ });
393
+ for (const _round of [1, 2]) for (const make of requests) await serve(make(), env);
394
+ if (differs.length > 0) throw new Error(differs.join("\n"));
395
+ if (store.size() === 0) throw new Error("checkCache: no request was a public read, so nothing was checked");
396
+ };
397
+ /**
180
398
  * The reader a page render reads through, in the same process: the request's
181
399
  * `RemoteClient`, answered by the server's own handlers with no HTTP between
182
400
  * them. Give it `serveFetch`'s config with the resolver a page's request
@@ -189,18 +407,28 @@ const serveFetch = (config) => {
189
407
  * refusal fails that Effect with `Unauthenticated`, as a 401 would. It only
190
408
  * reads: a mutation fails with `RemoteMutationError` and a live open with
191
409
  * `RemoteLiveError`, since a navigation can be started from another site.
410
+ *
411
+ * Each read is noted for a render `foldkit-ssr` may cache (`PageReads`):
412
+ * with `cache`, one proved public as `serveFetch` proves it is answered as
413
+ * `cache.visitor` and noted public; every other read, and every read without
414
+ * `cache`, is noted private, which keeps the page from being cached.
192
415
  */
193
- const pageReader = (config) => (request, env) => Layer.unwrap(Effect.map(config.resolvePrincipal(request, env), (principal) => {
194
- const handlers = RemoteServer.handlers(config.server, principal, {
416
+ const pageReader = (config) => {
417
+ refuseSomeone(config.server, config.cache);
418
+ const limits = {
195
419
  maxIdsPerEntity: config.maxIdsPerEntity,
196
420
  maxDepth: config.maxDepth
197
- });
198
- return Remote.clientLayer({
199
- ...handlers,
200
- FoldkitRemoteMutate: () => Effect.fail(new RemoteMutationError({ message: "A page render reads; it does not write" })),
201
- FoldkitRemoteLive: () => Stream.fail(new RemoteLiveError({ message: "A page render keeps no live stream" }))
202
- });
203
- })).pipe(Layer.provide(config.layer(env)));
204
- export { pageReader, serveFetch };
421
+ };
422
+ const visitor = Option.map(Option.fromUndefinedOr(config.cache), (cache) => RemoteServer.handlers(config.server, cache.visitor, limits));
423
+ return (request, env) => Layer.unwrap(Effect.map(config.resolvePrincipal(request, env), (principal) => {
424
+ const handlers = notingHandlers(config.server, RemoteServer.handlers(config.server, principal, limits), visitor);
425
+ return Remote.clientLayer({
426
+ ...handlers,
427
+ FoldkitRemoteMutate: () => Effect.fail(new RemoteMutationError({ message: "A page render reads; it does not write" })),
428
+ FoldkitRemoteLive: () => Stream.fail(new RemoteLiveError({ message: "A page render keeps no live stream" }))
429
+ });
430
+ })).pipe(Layer.provide(config.layer(env)));
431
+ };
432
+ export { checkCache, pageReader, serveFetch };
205
433
 
206
434
  //# sourceMappingURL=fetch.mjs.map