foldkit-remote-server 0.12.1 → 0.13.1

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
@@ -207,6 +207,11 @@ RemoteServer.entity(entity, {
207
207
  >,
208
208
 
209
209
  authorize?: (principal, fields) => readonly string[]
210
+
211
+ filter?: (principal, fields) => Effect<{
212
+ fields: readonly string[] // what to read: the allowed fields, and any the decision needs
213
+ apply: (record) => record // one record as the principal sees it
214
+ }, RemoteServerError, R>
210
215
  })
211
216
  ```
212
217
 
@@ -224,7 +229,17 @@ Important consequences:
224
229
  - ids shared by several selections are de-duplicated;
225
230
  - relation targets are fetched level by level and shared targets are not loaded
226
231
  repeatedly;
227
- - a relation the principal may not read is never followed.
232
+ - a relation the principal may not read is never followed;
233
+ - `authorize` decides per field, for every row alike; `filter` decides per
234
+ record, after `read`. It runs once per read (by id or live), may read
235
+ fields the client did not ask for so it can decide (an owner id, say),
236
+ and a member it drops from a record is settled like one the Source did not
237
+ return. `foldkit-guard` builds one from a member's guards.
238
+ - a Source, and a query Source, may carry `visible`: the rule that decides
239
+ which rows it returns, as it was given one (a Drizzle binding's `visible`,
240
+ `RemoteServer.memory`'s `readable`). The server never runs it; it is there
241
+ for a startup check such as `GuardServer.validate` to confirm a Source
242
+ applies the rule its Entity requires.
228
243
 
229
244
  The Source should still avoid reading or returning columns the request did not
230
245
  ask for. The handler filters returned values again, but the data boundary is the
@@ -418,7 +433,20 @@ const RenameProjectSource = RemoteServer.mutation(
418
433
  ```
419
434
 
420
435
  The input is decoded before the Source runs and the output is encoded before it
421
- crosses the wire. A Source may additionally return connection changes:
436
+ crosses the wire. A Source refuses with a value of the mutation's `Refusal`:
437
+ `Effect.fail(RemoteServer.refuse(SetPrice, { _tag: 'Field', key: 'price', reason: 'too low' }))`.
438
+ The value is type-checked against that mutation, encoded by its schema, and
439
+ sent beside a message (a 422 over JSON); a refusal made for another mutation,
440
+ or not one the mutation declares, is sent as an invalid refusal instead.
441
+
442
+ A refusal of who is asking, rather than of what they asked, is
443
+ `Effect.fail(RemoteServer.forbid('Only an admin may archive.'))`: sent as
444
+ `Forbidden` with the reason (a 403 over JSON), or with none when `forbid()` is
445
+ given none, so the refusal says nothing of why. It is the same for every
446
+ mutation, so it needs no `Refusal` declared. The Source is also given `requestId`, the client's id for the
447
+ request, which is the same on every retry of it: record a write under it, and a
448
+ retry can find that the write was made. Nothing deduplicates by it yet. A Source
449
+ may additionally return connection changes:
422
450
 
423
451
  ```ts
424
452
  RemoteServer.prepend(connection, Project.ref(id))
@@ -429,6 +457,33 @@ RemoteServer.remove(connection, Project.ref(id))
429
457
  Those confirmed changes replace the corresponding optimistic connection layers
430
458
  on the client.
431
459
 
460
+ A mutation declared as a `Write` (`Mutation.write`) needs no handler.
461
+ `RemoteServer.write(mutation, writer)` binds the input to the write, only the
462
+ keys the client named when it named some, and hands the row's id and new values
463
+ to an `EntityWriter`, which writes them and answers the row as written:
464
+
465
+ ```ts
466
+ RemoteServer.write(EditProject, writer(Db.Project)) // `writer` from foldkit-remote-drizzle
467
+ ```
468
+
469
+ The answer is the mutation's patch, or for a delete its deletion. With
470
+ `expect`, the writer is told the revision the row was read at; no row at it is
471
+ refused as `Refusal.conflict`. An update of no row fails; an insert of an id
472
+ already holding what it writes answers that row, and a delete of a row already
473
+ gone succeeds, so a retry of either is safe. An insert of an id holding
474
+ anything else fails: that row is not its answer. The writer must be for the write's own Entity,
475
+ which is checked where the mutation is served.
476
+
477
+ A writer with a `read` (the row as a principal may see it, under the read
478
+ rule its Source applies) answers through it: the patch is the written row as
479
+ its writer now sees it, and a row the write moved out of their sight answers
480
+ in `deleted`, so the client takes it out of every list rather than placing
481
+ it where the server would not list it. A writer may refuse with
482
+ `RemoteServer.forbid`, as `foldkit-guard`'s `GuardServer.writer` does. Its
483
+ `linked` answers a row's links as stored, whatever a reader may see of the
484
+ rows they point at, so such a guard can tell a write that unlinks a hidden row
485
+ from one that changes nothing; `foldkit-remote-drizzle`'s `writer` has both.
486
+
432
487
  Remote mutations are immediate requests against **server-owned** state. They are
433
488
  not a durable offline intent log; client-authored edits that must survive offline
434
489
  belong to `foldkit-sync`.
@@ -459,8 +514,10 @@ the client planner can fall back to refetching it.
459
514
 
460
515
  ### Let a `liveHub` re-read changed fields
461
516
 
462
- When your infrastructure can say **what changed** but does not naturally produce
463
- Remote patches, use a hub:
517
+ A hub fans **what changed** out to live subscribers. Give it to the handlers,
518
+ and every mutation's answer is published to it: each patch as a change of the
519
+ fields it carries, each deletion as a deletion. A mutation Source names nothing
520
+ twice.
464
521
 
465
522
  ```ts
466
523
  const entitySources = [ProjectSource]
@@ -470,19 +527,78 @@ const handlers = RemoteServer.handlers(Server, principal, {
470
527
  live: hub,
471
528
  })
472
529
 
473
- // From a mutation Source, database trigger consumer, etc.
530
+ // Only for a write that is not a mutation: a database trigger consumer, a job.
474
531
  yield* hub.changed(Project.ref(projectId), ['status', 'updatedAt'])
475
532
  yield* hub.deleted(Project.ref(projectId))
476
533
  ```
477
534
 
535
+ A mutation's publish runs after its Source returned, so after a write that
536
+ commits as it goes. A failed publish is logged and the mutation still answers:
537
+ its write has happened, and a failed answer would be retried.
538
+
478
539
  The hub remembers each subscriber's requirements and principal. `changed`:
479
540
 
480
541
  1. intersects the changed fields with what each subscriber selected;
481
542
  2. re-reads only that intersection through the Entity Source;
482
543
  3. applies that subscriber's authorization again;
483
- 4. emits the resulting patch with a continuing cursor.
544
+ 4. emits the resulting patch with a continuing cursor, or a deletion where
545
+ the re-read no longer finds the row: deleted, or moved out of that
546
+ subscriber's sight.
547
+
548
+ `deleted` asks each subscriber again too, for every field it selects: a row
549
+ deleted for one writer may only be hidden from them, so a subscriber that
550
+ still reads it is sent what it now sees, and only one it is gone for a
551
+ deletion. One subscriber's failed read does not keep the others from theirs;
552
+ the call fails once they are sent.
553
+
554
+ Subscribers that selected none of the changed fields do no work, and
555
+ subscribers with one principal share one re-read. One principal means the same
556
+ value, unless the hub is given a `key`: then two requests whose principals
557
+ have one key, each with a principal object of its own, share it, read as the
558
+ first of them. A key must therefore name everything the Sources decide by:
484
559
 
485
- Subscribers that selected none of the changed fields do no work.
560
+ ```ts
561
+ const hub = yield* RemoteServer.liveHub(entitySources, {
562
+ key: user => (user.isAdmin ? 'admin' : 'member'),
563
+ })
564
+ ```
565
+
566
+ #### Fields every principal reads alike
567
+
568
+ A re-read per principal is how the hub stays exact when who is asking decides
569
+ what a row shows. Where nothing does, a Source can say so, and the hub sends a
570
+ written value as it is:
571
+
572
+ ```ts
573
+ // Everyone reads a project's name alike; only an admin reads its private notes.
574
+ const SharedProjectSource = RemoteServer.entity<Principal>(Project, {
575
+ authorize: ProjectSource.authorize,
576
+ read: ProjectSource.read,
577
+ shared: ['name'],
578
+ })
579
+ ```
580
+
581
+ - `shared` names fields every principal reads alike, of every row: no rule
582
+ about who is asking hides the row or the field, or changes its value. The
583
+ server trusts it, so declare it only where that holds; a field the Source
584
+ does not serve is refused when the Source is made.
585
+ - `hub.changed(ref, fields, values)` takes the row's stored values. A
586
+ `shared` field among them goes to each subscriber that selected it with no
587
+ read; the rest are re-read as above. A field a subscriber pages with a
588
+ window is always re-read.
589
+ - The handlers pass a declared write's answer (`RemoteServer.write`), which
590
+ is the row as stored. A handler's answer is its own claim, so its fields are
591
+ re-read.
592
+ - `foldkit-remote-drizzle`'s `source` and `RemoteServer.memory` take it too,
593
+ and `foldkit-guard`'s `GuardServer.validate` refuses a shared field a Read
594
+ rule could tell readers apart by.
595
+
596
+ A hub is an in-memory fan-out, so whatever calls `changed` must be able to wake
597
+ the subscriber's fiber. In a worker it cannot: one request cannot wake another's
598
+ stream, so a hub fed from a second request delivers nothing and tears the first
599
+ stream down (see `AGENTS.md`). On Workers, poll the shared store from inside the
600
+ subscriber's own request instead — `examples/cloudflare` has the shape. A hub is
601
+ right for a long-lived server process that owns both sides.
486
602
 
487
603
  A hand-written live Source and a hub number their events independently. Use one
488
604
  or the other for a given subscription path rather than mixing cursor domains.
@@ -507,6 +623,20 @@ authorization
507
623
 
508
624
  `RemoteServer.handlers(Server, principal)` deliberately receives a resolved
509
625
  principal. It does not inspect headers, sessions, cookies, or bearer tokens.
626
+ The principal is a value, or a Context key that each call reads, so one
627
+ handler set (one RPC layer) answers every request and authentication provides
628
+ the key per request:
629
+
630
+ ```ts
631
+ class CurrentUser extends Context.Service<CurrentUser, Principal>()('app/CurrentUser') {}
632
+ const handlers = RemoteServer.handlers(Server, CurrentUser)
633
+
634
+ // per request, once authentication has resolved `user`
635
+ RemoteServer.answer(handlers, body).pipe(Effect.provideService(CurrentUser, user))
636
+ ```
637
+
638
+ Every handler then needs `CurrentUser`, which the types carry: a key holding
639
+ another type than the Server's principal is a type error.
510
640
 
511
641
  For Entity reads:
512
642
 
@@ -550,7 +680,8 @@ RemoteServer.validate(Data, Server)
550
680
  That catches an Entity, Query, or Mutation Source whose name is not declared by
551
681
  the shared domain instead of letting it silently answer nothing at runtime.
552
682
 
553
- Then compile once per authenticated principal:
683
+ Then compile it into handlers, once per principal, or once for every request
684
+ with a Context key as the principal (see Authentication vs authorization):
554
685
 
555
686
  ```ts
556
687
  const handlers = RemoteServer.handlers(Server, principal, {
@@ -685,6 +816,27 @@ A withheld field is settled, as from any server: the client stops asking for
685
816
  it, and a selection that needs it fails as `Unavailable`. A name in
686
817
  `authorize` the domain does not declare is refused when the backend is made.
687
818
 
819
+ `filter` takes the same per-entity form. `readable` decides which rows a
820
+ principal may read, once per read, given each row's stored values; its second
821
+ argument looks another stored row up by id, for a rule that follows a
822
+ relation:
823
+
824
+ ```ts
825
+ // Only an admin reads projects.
826
+ const adminsOnly = RemoteServer.memory({
827
+ domain: Data,
828
+ rows: { Project: [{ id: 'p1', name: 'Apollo', privateNotes: 'Internal' }] },
829
+ principal: { isAdmin: false },
830
+ readable: (principal: Principal) =>
831
+ Effect.succeed(entity => principal.isAdmin || entity !== 'Project'),
832
+ })
833
+ ```
834
+
835
+ A row it may not read is absent from a read by id (the client reads it as
836
+ not found) and from every query, and a ref to it is dropped from a relation:
837
+ a list leaves it out and a `one` ref reads `null`, as a database binding's
838
+ `visible` hides it.
839
+
688
840
  ## Over a MessagePort
689
841
 
690
842
  `servePort(handlers, port)` from `foldkit-remote-server/port` answers
@@ -734,6 +886,50 @@ It binds no principal: pass the `handlers` for the request's own,
734
886
  established by your authentication, as everywhere else. It carries no live
735
887
  data.
736
888
 
889
+ ## Over fetch (Workers)
890
+
891
+ `serveFetch` from `foldkit-remote-server/fetch` is that route as a value: a
892
+ `(request: Request, env: Env) => Promise<Response>` for a Worker's `fetch`,
893
+ or any other runtime that speaks `Request`/`Response`. The principal is
894
+ resolved per request, and the Sources' requirements are provided per request
895
+ from the environment:
896
+
897
+ ```ts
898
+ import { serveFetch } from 'foldkit-remote-server/fetch'
899
+
900
+ export default {
901
+ fetch: serveFetch({
902
+ server,
903
+ resolvePrincipal: request => ({ actorId: request.headers.get('x-actor') ?? 'anon' }),
904
+ layer: env => databaseLayer(drizzle(env.DB)),
905
+ }),
906
+ }
907
+ ```
908
+
909
+ Only `POST`s to `path` (default `/remote`) are answered; anything else is a 404. A body that is not JSON, or not a request, is a 400 that reaches no
910
+ handler; a handler's failure a 500 with its message. A principal resolution
911
+ that throws is a 401 with its message; anything else this side breaks,
912
+ including layer provision, a 500 that says nothing of it.
913
+
914
+ A body that opens live (`{ operation: 'live', payload }`) is answered with
915
+ the stream as `text/event-stream`: one `data:` frame per `LiveChange`, then
916
+ a terminal `event: error` frame carrying the failure's message when the
917
+ stream fails rather than ends. A payload no live stream speaks is a 400 that
918
+ subscribes to nothing. `Remote.httpWithLive` is the other end; a client that
919
+ disconnects interrupts the subscription, as closing the RPC stream would.
920
+
921
+ The stream moves on its own even when nothing changes: a `: ping` comment opens
922
+ it, and another follows every `liveHeartbeat` (default 15 seconds), so proxies
923
+ and worker runtimes do not drop an idle connection. The heartbeat stops with
924
+ the events it serves, so a stream with nothing to serve still ends.
925
+
926
+ `live` takes a hub whose `changed`/`deleted` signals reach these streams. What
927
+ calls it must be able to wake the subscriber's fiber: in a worker, one request
928
+ cannot wake another's stream, so a hub fed from a second request delivers
929
+ nothing and ends the first stream. Poll the shared store from inside the
930
+ subscriber's own request instead — `examples/cloudflare`'s `pollLive` is the
931
+ shape. A hub is right for a long-lived process that owns both sides.
932
+
737
933
  ## What it does not own
738
934
 
739
935
  `foldkit-remote-server` intentionally does **not** own:
@@ -758,3 +954,5 @@ than another application runtime.
758
954
  Query windows into Drizzle reads.
759
955
  - [`examples/kitchen-sink`](../../examples/kitchen-sink) — Remote +
760
956
  RemoteServer + Drizzle + `liveHub` in one executable trace.
957
+ - [`examples/cloudflare`](../../examples/cloudflare) — Remote + Sync +
958
+ remote-drizzle on D1 in a real worker, with a polling live Source.
@@ -0,0 +1,42 @@
1
+ import { LiveHub, ServerDefinition } from "./index.mjs";
2
+ import { Duration, Layer } from "effect";
3
+ //#region src/fetch.d.ts
4
+ /** What `serveFetch` needs of the host runtime, per request. */
5
+ export interface FetchConfig<P, R, Env> {
6
+ /** The server definition, as `RemoteServer.make` built it. */
7
+ readonly server: ServerDefinition<P, R>;
8
+ /** Who this request is, from the request and the environment. May throw. */
9
+ readonly resolvePrincipal: (request: Request, env: Env) => P | Promise<P>;
10
+ /** What the Sources need, from the environment. Kept cheap: built per request. */
11
+ readonly layer: (env: Env) => Layer.Layer<R>;
12
+ /** The path answered; anything else is a 404. Default `/remote`. */
13
+ readonly path?: string | undefined;
14
+ /** A hub whose `changed`/`deleted` signals reach the live streams this serves. */
15
+ readonly live?: LiveHub<P, R> | undefined;
16
+ /** A heartbeat comment every this often, keeping idle streams alive through proxies. Default 15 seconds. */
17
+ readonly liveHeartbeat?: Duration.Input | undefined;
18
+ /** A read batch may not name more ids of one entity than this; default 1000. */
19
+ readonly maxIdsPerEntity?: number | undefined;
20
+ /** A nested selection may not reach further than this many levels; default 8. */
21
+ readonly maxDepth?: number | undefined;
22
+ }
23
+ /**
24
+ * Answers Remote `POST`s with `Response`s: what a Worker's `fetch` hands to
25
+ * the route. A body that is not JSON, or not a request, is a 400 that reaches
26
+ * no handler; a handler's failure a 500 with its message; anything this side
27
+ * breaks, including principal resolution and layer provision, a 500 that says
28
+ * nothing of it. A live open is answered with the stream instead.
29
+ *
30
+ * ```ts
31
+ * export default {
32
+ * fetch: serveFetch({
33
+ * server,
34
+ * resolvePrincipal: request => ({ actorId: request.headers.get('x-actor') ?? 'anon' }),
35
+ * layer: env => databaseLayer(drizzle(env.DB)),
36
+ * }),
37
+ * }
38
+ * ```
39
+ */
40
+ export declare const serveFetch: <P, R, Env>(config: FetchConfig<P, R, Env>) => ((request: Request, env: Env) => Promise<Response>);
41
+ //#endregion
42
+ //# sourceMappingURL=fetch.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"fetch.d.mts","names":[],"sources":["../src/fetch.ts"],"mappings":";;;;iBAkBiB,YAAY,GAAG,GAAG;;WAExB,QAAQ,iBAAiB,GAAG;;WAE5B,mBAAmB,SAAS,SAAS,KAAK,QAAQ,IAAI,QAAQ;;WAE9D,QAAQ,KAAK,QAAQ,MAAM,MAAM;;WAEjC;;WAEA,OAAO,QAAQ,GAAG;;WAElB,gBAAgB,SAAS;;WAEzB;;WAEA;;;;;;;;;;;;;;;;;;;qBAgHE,aAAc,GAAG,GAAG,KAC/B,QAAQ,YAAY,GAAG,GAAG,WACvB,SAAS,SAAS,KAAK,QAAQ,QAAQ"}
package/dist/fetch.mjs ADDED
@@ -0,0 +1,126 @@
1
+ import { RemoteServer } from "./index.mjs";
2
+ import { Deferred, Effect, Schedule, Schema, Stream } from "effect";
3
+ import { LiveRequirement } from "foldkit-remote";
4
+ //#region src/fetch.ts
5
+ /**
6
+ * `foldkit-remote-server/fetch`: `RemoteServer` over the Fetch API, for
7
+ * Cloudflare Workers and any other runtime that speaks `Request`/`Response`.
8
+ *
9
+ * Reads, queries, and mutations ride one `POST` each, as `Remote.http` sends
10
+ * them and `RemoteServer.answer` answers them. Live requirements ride one
11
+ * `POST` that answers with a `text/event-stream` of `LiveChange` frames, one
12
+ * `data:` frame per change and a terminal `event: error` frame when the
13
+ * stream fails; `Remote.httpWithLive` is the other end. The principal is
14
+ * resolved per request, from whatever the runtime hands over (a header, a
15
+ * binding, a session), and the Sources' requirements are provided per
16
+ * request from the environment (a D1 binding, a connection string).
17
+ */
18
+ /** A live open over fetch: the requirements and the cursor it resumes after. */
19
+ const LiveFetchRequest = Schema.Struct({
20
+ operation: Schema.Literal("live"),
21
+ payload: Schema.Unknown
22
+ });
23
+ /** A terminal stream failure, so the client fails with its message instead of hanging. */
24
+ const errorFrame = (message) => `event: error\ndata: ${JSON.stringify({ message })}\n\n`;
25
+ /**
26
+ * The live stream as SSE bytes: one `data:` frame per change, then a
27
+ * terminal `event: error` frame when the stream fails rather than ends. A
28
+ * `: ping` comment opens the stream, so headers and a first byte reach the
29
+ * client at once, and rides along every `heartbeat` so a stream with nothing
30
+ * to say still moves: workers cancel responses that go quiet, and proxies
31
+ * drop idle connections. The heartbeat ends with the events, so a stream
32
+ * with nothing to serve still ends. A client that disconnects interrupts
33
+ * the subscription, as closing the RPC stream would.
34
+ */
35
+ const liveBytes = (handlers, payload, heartbeat) => Stream.unwrap(Effect.gen(function* () {
36
+ const ended = yield* Deferred.make();
37
+ const events = handlers.FoldkitRemoteLive(payload).pipe(Stream.map((change) => `data: ${JSON.stringify(change)}\n\n`), Stream.catchTags({
38
+ RemoteLiveError: (error) => Stream.succeed(errorFrame(error.message)),
39
+ RemoteProtocolError: (error) => Stream.succeed(errorFrame(error.message))
40
+ }), Stream.ensuring(Deferred.succeed(ended, void 0)));
41
+ const beats = Stream.concat(Stream.succeed(": ping\n\n"), Stream.fromSchedule(Schedule.spaced(heartbeat)).pipe(Stream.map(() => ": ping\n\n"))).pipe(Stream.interruptWhen(Deferred.await(ended)));
42
+ return Stream.merge(events, beats);
43
+ })).pipe(Stream.encodeText);
44
+ /**
45
+ * Whether the body opens a live stream rather than asking `answer`. Anything
46
+ * else, including a body that is not a request at all, is `answer`'s to
47
+ * refuse with a 400.
48
+ */
49
+ const isLiveOpen = (body) => {
50
+ try {
51
+ return Schema.decodeUnknownSync(LiveFetchRequest)(body).operation === "live";
52
+ } catch {
53
+ return false;
54
+ }
55
+ };
56
+ /** Heartbeats when the caller names none: under proxy idle timeouts. */
57
+ const DEFAULT_HEARTBEAT = "15 seconds";
58
+ /**
59
+ * Answers a live open with the stream as `text/event-stream`. A payload no
60
+ * live stream speaks is a 400 that subscribes to nothing; anything this side
61
+ * breaks building the stream is a 500 that says nothing of it. Once the
62
+ * stream runs, its own failures are its terminal `event: error` frame.
63
+ */
64
+ const liveResponse = (handlers, payload, layer, heartbeat) => {
65
+ let requirement;
66
+ try {
67
+ requirement = Schema.decodeUnknownSync(LiveRequirement)(payload);
68
+ } catch {
69
+ return Promise.resolve(Response.json({ error: "The live payload is not a requirement" }, { status: 400 }));
70
+ }
71
+ return Effect.runPromise(Stream.toReadableStreamEffect(liveBytes(handlers, requirement, heartbeat)).pipe(Effect.provide(layer), Effect.map((body) => new Response(body, { headers: {
72
+ "content-type": "text/event-stream",
73
+ "cache-control": "no-cache"
74
+ } })))).catch(() => Response.json({ error: "Internal error" }, { status: 500 }));
75
+ };
76
+ /**
77
+ * Answers Remote `POST`s with `Response`s: what a Worker's `fetch` hands to
78
+ * the route. A body that is not JSON, or not a request, is a 400 that reaches
79
+ * no handler; a handler's failure a 500 with its message; anything this side
80
+ * breaks, including principal resolution and layer provision, a 500 that says
81
+ * nothing of it. A live open is answered with the stream instead.
82
+ *
83
+ * ```ts
84
+ * export default {
85
+ * fetch: serveFetch({
86
+ * server,
87
+ * resolvePrincipal: request => ({ actorId: request.headers.get('x-actor') ?? 'anon' }),
88
+ * layer: env => databaseLayer(drizzle(env.DB)),
89
+ * }),
90
+ * }
91
+ * ```
92
+ */
93
+ const serveFetch = (config) => {
94
+ const path = config.path ?? "/remote";
95
+ return async (request, env) => {
96
+ if (request.method !== "POST" || new URL(request.url).pathname !== path) return Response.json({ error: "not found" }, { status: 404 });
97
+ let principal;
98
+ try {
99
+ principal = await config.resolvePrincipal(request, env);
100
+ } catch (error) {
101
+ return Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 401 });
102
+ }
103
+ let body;
104
+ try {
105
+ body = await request.json();
106
+ } catch {
107
+ return Response.json({ error: "The body is not JSON" }, { status: 400 });
108
+ }
109
+ const handlers = RemoteServer.handlers(config.server, principal, {
110
+ live: config.live,
111
+ maxIdsPerEntity: config.maxIdsPerEntity,
112
+ maxDepth: config.maxDepth
113
+ });
114
+ if (isLiveOpen(body)) return liveResponse(handlers, body.payload, config.layer(env), config.liveHeartbeat ?? DEFAULT_HEARTBEAT);
115
+ try {
116
+ const answered = await Effect.runPromise(RemoteServer.answer(handlers, body).pipe(Effect.provide(config.layer(env))));
117
+ return Response.json(answered.body, { status: answered.status });
118
+ } catch {
119
+ return Response.json({ error: "Internal error" }, { status: 500 });
120
+ }
121
+ };
122
+ };
123
+ //#endregion
124
+ export { serveFetch };
125
+
126
+ //# sourceMappingURL=fetch.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"fetch.mjs","names":[],"sources":["../src/fetch.ts"],"sourcesContent":["/**\n * `foldkit-remote-server/fetch`: `RemoteServer` over the Fetch API, for\n * Cloudflare Workers and any other runtime that speaks `Request`/`Response`.\n *\n * Reads, queries, and mutations ride one `POST` each, as `Remote.http` sends\n * them and `RemoteServer.answer` answers them. Live requirements ride one\n * `POST` that answers with a `text/event-stream` of `LiveChange` frames, one\n * `data:` frame per change and a terminal `event: error` frame when the\n * stream fails; `Remote.httpWithLive` is the other end. The principal is\n * resolved per request, from whatever the runtime hands over (a header, a\n * binding, a session), and the Sources' requirements are provided per\n * request from the environment (a D1 binding, a connection string).\n */\nimport { Deferred, Effect, Schedule, Schema, Stream, type Duration, type Layer } from 'effect'\nimport { LiveRequirement, type RemoteRpcClient } from 'foldkit-remote'\nimport { RemoteServer, type LiveHub, type ServerDefinition } from './index.js'\n\n/** What `serveFetch` needs of the host runtime, per request. */\nexport interface FetchConfig<P, R, Env> {\n /** The server definition, as `RemoteServer.make` built it. */\n readonly server: ServerDefinition<P, R>\n /** Who this request is, from the request and the environment. May throw. */\n readonly resolvePrincipal: (request: Request, env: Env) => P | Promise<P>\n /** What the Sources need, from the environment. Kept cheap: built per request. */\n readonly layer: (env: Env) => Layer.Layer<R>\n /** The path answered; anything else is a 404. Default `/remote`. */\n readonly path?: string | undefined\n /** A hub whose `changed`/`deleted` signals reach the live streams this serves. */\n readonly live?: LiveHub<P, R> | undefined\n /** A heartbeat comment every this often, keeping idle streams alive through proxies. Default 15 seconds. */\n readonly liveHeartbeat?: Duration.Input | undefined\n /** A read batch may not name more ids of one entity than this; default 1000. */\n readonly maxIdsPerEntity?: number | undefined\n /** A nested selection may not reach further than this many levels; default 8. */\n readonly maxDepth?: number | undefined\n}\n\n/** A live open over fetch: the requirements and the cursor it resumes after. */\nconst LiveFetchRequest = Schema.Struct({\n operation: Schema.Literal('live'),\n payload: Schema.Unknown,\n})\n\n/** A terminal stream failure, so the client fails with its message instead of hanging. */\nconst errorFrame = (message: string): string =>\n `event: error\\ndata: ${JSON.stringify({ message })}\\n\\n`\n\n/**\n * The live stream as SSE bytes: one `data:` frame per change, then a\n * terminal `event: error` frame when the stream fails rather than ends. A\n * `: ping` comment opens the stream, so headers and a first byte reach the\n * client at once, and rides along every `heartbeat` so a stream with nothing\n * to say still moves: workers cancel responses that go quiet, and proxies\n * drop idle connections. The heartbeat ends with the events, so a stream\n * with nothing to serve still ends. A client that disconnects interrupts\n * the subscription, as closing the RPC stream would.\n */\nconst liveBytes = <R>(\n handlers: RemoteRpcClient<R>,\n payload: Schema.Schema.Type<typeof LiveRequirement>,\n heartbeat: Duration.Input,\n): Stream.Stream<Uint8Array, never, R> =>\n Stream.unwrap(\n Effect.gen(function* () {\n const ended = yield* Deferred.make<void>()\n const events = handlers.FoldkitRemoteLive(payload).pipe(\n Stream.map(change => `data: ${JSON.stringify(change)}\\n\\n`),\n Stream.catchTags({\n RemoteLiveError: error => Stream.succeed(errorFrame(error.message)),\n RemoteProtocolError: error => Stream.succeed(errorFrame(error.message)),\n }),\n Stream.ensuring(Deferred.succeed(ended, undefined)),\n )\n const beats = Stream.concat(\n Stream.succeed(': ping\\n\\n'),\n Stream.fromSchedule(Schedule.spaced(heartbeat)).pipe(Stream.map(() => ': ping\\n\\n')),\n ).pipe(Stream.interruptWhen(Deferred.await(ended)))\n return Stream.merge(events, beats)\n }),\n ).pipe(Stream.encodeText)\n\n/**\n * Whether the body opens a live stream rather than asking `answer`. Anything\n * else, including a body that is not a request at all, is `answer`'s to\n * refuse with a 400.\n */\nconst isLiveOpen = (body: unknown): body is Schema.Schema.Type<typeof LiveFetchRequest> => {\n try {\n return Schema.decodeUnknownSync(LiveFetchRequest)(body).operation === 'live'\n } catch {\n return false\n }\n}\n\n/** Heartbeats when the caller names none: under proxy idle timeouts. */\nconst DEFAULT_HEARTBEAT: Duration.Input = '15 seconds'\n\n/**\n * Answers a live open with the stream as `text/event-stream`. A payload no\n * live stream speaks is a 400 that subscribes to nothing; anything this side\n * breaks building the stream is a 500 that says nothing of it. Once the\n * stream runs, its own failures are its terminal `event: error` frame.\n */\nconst liveResponse = <R>(\n handlers: RemoteRpcClient<R>,\n payload: unknown,\n layer: Layer.Layer<R>,\n heartbeat: Duration.Input,\n): Promise<Response> => {\n let requirement: Schema.Schema.Type<typeof LiveRequirement>\n try {\n requirement = Schema.decodeUnknownSync(LiveRequirement)(payload)\n } catch {\n return Promise.resolve(\n Response.json({ error: 'The live payload is not a requirement' }, { status: 400 }),\n )\n }\n return Effect.runPromise(\n Stream.toReadableStreamEffect(liveBytes(handlers, requirement, heartbeat)).pipe(\n Effect.provide(layer),\n Effect.map(\n body =>\n new Response(body, {\n headers: { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' },\n }),\n ),\n ),\n ).catch(() => Response.json({ error: 'Internal error' }, { status: 500 }))\n}\n/**\n * Answers Remote `POST`s with `Response`s: what a Worker's `fetch` hands to\n * the route. A body that is not JSON, or not a request, is a 400 that reaches\n * no handler; a handler's failure a 500 with its message; anything this side\n * breaks, including principal resolution and layer provision, a 500 that says\n * nothing of it. A live open is answered with the stream instead.\n *\n * ```ts\n * export default {\n * fetch: serveFetch({\n * server,\n * resolvePrincipal: request => ({ actorId: request.headers.get('x-actor') ?? 'anon' }),\n * layer: env => databaseLayer(drizzle(env.DB)),\n * }),\n * }\n * ```\n */\nexport const serveFetch = <P, R, Env>(\n config: FetchConfig<P, R, Env>,\n): ((request: Request, env: Env) => Promise<Response>) => {\n const path = config.path ?? '/remote'\n return async (request, env) => {\n if (request.method !== 'POST' || new URL(request.url).pathname !== path) {\n return Response.json({ error: 'not found' }, { status: 404 })\n }\n let principal: P\n try {\n principal = await config.resolvePrincipal(request, env)\n } catch (error) {\n return Response.json(\n { error: error instanceof Error ? error.message : String(error) },\n { status: 401 },\n )\n }\n let body: unknown\n try {\n body = await request.json()\n } catch {\n return Response.json({ error: 'The body is not JSON' }, { status: 400 })\n }\n // Bound per request: the principal is the request's own, as everywhere else.\n const handlers = RemoteServer.handlers(config.server, principal, {\n live: config.live,\n maxIdsPerEntity: config.maxIdsPerEntity,\n maxDepth: config.maxDepth,\n })\n if (isLiveOpen(body)) {\n return liveResponse(\n handlers,\n body.payload,\n config.layer(env),\n config.liveHeartbeat ?? DEFAULT_HEARTBEAT,\n )\n }\n try {\n const answered = await Effect.runPromise(\n RemoteServer.answer(handlers, body).pipe(Effect.provide(config.layer(env))),\n )\n return Response.json(answered.body, { status: answered.status })\n } catch {\n // A failure of the layer, or a defect anywhere: this side broke, and the\n // caller learns that it did, not what. `answer` already maps its own\n // failures and defects to 400/500 answers above this.\n return Response.json({ error: 'Internal error' }, { status: 500 })\n }\n }\n}\n"],"mappings":"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"}