foldkit-remote-server 0.12.0 → 0.13.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 +206 -8
- package/dist/fetch.d.mts +42 -0
- package/dist/fetch.d.mts.map +1 -0
- package/dist/fetch.mjs +126 -0
- package/dist/fetch.mjs.map +1 -0
- package/dist/index.d.mts +217 -25
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +512 -241
- package/dist/index.mjs.map +1 -1
- package/package.json +9 -4
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
|
|
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
|
-
|
|
463
|
-
|
|
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
|
-
//
|
|
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
|
-
|
|
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
|
|
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.
|
package/dist/fetch.d.mts
ADDED
|
@@ -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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"}
|