foldkit-remote-server 0.12.1 → 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/dist/index.mjs CHANGED
@@ -1,15 +1,29 @@
1
- import { Effect, Queue, Schema, Stream } from "effect";
2
- import { QueryEvaluateError, assertSupported, evaluate, evaluate as evaluate$1, supported } from "foldkit-entity";
3
- import { MutationRequest, QueryRequest, RELATION_ALIAS, REMOTE_PROTOCOL_VERSION, ReadBatch, Remote, RemoteJsonRequest, RemoteLiveError, RemoteMutationError, RemoteProtocolError, RemoteQueryError, RemoteReadError, Requirement, aliasedField, connectionIdentity, entityKey, refsIn, stableStringify } from "foldkit-remote";
1
+ import { Context, Effect, Match, Option, Queue, Schema, Stream } from "effect";
2
+ import { QueryEvaluateError, Write, assertSupported, evaluate, evaluate as evaluate$1, supported } from "foldkit-entity";
3
+ import { MutationRequest, QueryRequest, RELATION_ALIAS, REMOTE_PROTOCOL_VERSION, ReadBatch, Remote, RemoteForbidden, RemoteJsonRequest, RemoteLiveError, RemoteMutationError, RemoteProtocolError, RemoteQueryError, RemoteReadError, Requirement, aliasedField, connectionIdentity, entityKey, refParts, refsIn, relationShape, stableStringify } from "foldkit-remote";
4
4
  //#region src/index.ts
5
5
  /**
6
6
  * `foldkit-remote-server` — server-side Sources and handler compilation.
7
7
  *
8
8
  * Owns entity/query Sources, **selection authorization**, normalization, and
9
9
  * turning them into Effect RPC handlers. It does not own HTTP, serialization, or
10
- * auth protocol; `principal` is resolved outside and passed in.
10
+ * auth protocol; `principal` is resolved outside, and passed in or provided.
11
11
  */
12
12
  var RemoteServerError = class extends Schema.TaggedError()("RemoteServerError", { message: Schema.String }) {};
13
+ /**
14
+ * A mutation Source's refusal, as the value its descriptor's `Refusal`
15
+ * declares: made with `RemoteServer.refuse`, which checks the value's type
16
+ * against the mutation, and sent to the client encoded, beside a message.
17
+ */
18
+ var MutationRefused = class extends Schema.TaggedError()("MutationRefused", {
19
+ /** The mutation the refusal was made for: a Source refusing as another is a bug. */
20
+ mutation: Schema.String,
21
+ refusal: Schema.Unknown,
22
+ /** What a person reads: the error's message beside the refusal. */
23
+ message: Schema.String
24
+ }) {};
25
+ /** `source.read` of `fields`, through the source's `filter` when it has one. */
26
+ const readFiltered = (source, principal, fields, read) => source.filter === void 0 ? read(fields) : Effect.flatMap(source.filter(principal, fields), (plan) => Effect.map(read(plan.fields), (records) => records.map(plan.apply)));
13
27
  const connectionChange = (connection, ref, position) => {
14
28
  const edge = {
15
29
  entity: ref.entity,
@@ -79,7 +93,8 @@ const checkIdsPerEntity = (requirements, maxIds) => {
79
93
  if (seen.size > maxIds) return requirement.entity;
80
94
  }
81
95
  };
82
- const liveHub = (entities) => Effect.sync(() => {
96
+ const liveHub = (entities, options = {}) => Effect.sync(() => {
97
+ const keyOf = options.key ?? ((principal) => principal);
83
98
  const sources = new Map(entities.map((source) => [source.entity, source]));
84
99
  const subscribers = /* @__PURE__ */ new Set();
85
100
  const emit = (subscriber, change) => {
@@ -89,6 +104,116 @@ const liveHub = (entities) => Effect.sync(() => {
89
104
  cursor: subscriber.cursor
90
105
  });
91
106
  };
107
+ /**
108
+ * Re-reads row `ref` for each subscriber that selects it, of `which` of
109
+ * its fields (none: every field it selects), and sends what it now sees:
110
+ * a patch, or, where the row is no longer there to it, a deletion. One
111
+ * group's failed read fails the call after the others are sent.
112
+ */
113
+ const refresh = (ref, which, values) => Effect.gen(function* () {
114
+ const key = `${ref.entity}:${ref.id}`;
115
+ const source = sources.get(ref.entity);
116
+ if (source === void 0) {
117
+ if (Option.isSome(which)) return;
118
+ for (const subscriber of subscribers) if (subscriber.selected.has(key)) yield* emit(subscriber, {
119
+ _tag: "EntityDeleted",
120
+ entity: ref.entity,
121
+ id: ref.id
122
+ });
123
+ return;
124
+ }
125
+ const given = (field) => values !== void 0 && source.shared !== void 0 && source.shared.has(field) && Object.hasOwn(values, field);
126
+ const groups = /* @__PURE__ */ new Map();
127
+ for (const subscriber of subscribers) {
128
+ const selected = subscriber.selected.get(key);
129
+ if (selected === void 0) continue;
130
+ const fields = Option.getOrElse(which, () => [...new Set([...selected.fields].map(aliasedField))]);
131
+ const principalKey = keyOf(subscriber.principal);
132
+ const sharing = groups.get(principalKey) ?? {
133
+ principal: subscriber.principal,
134
+ byWindows: /* @__PURE__ */ new Map()
135
+ };
136
+ groups.set(principalKey, sharing);
137
+ const { byWindows } = sharing;
138
+ const join = (windows, renames, wanted) => {
139
+ const groupKey = `${stableStringify(windows)}\u0000${stableStringify(renames)}`;
140
+ const group = byWindows.get(groupKey) ?? {
141
+ windows,
142
+ renames,
143
+ entries: []
144
+ };
145
+ byWindows.set(groupKey, group);
146
+ group.entries.push({
147
+ subscriber,
148
+ fields: wanted
149
+ });
150
+ };
151
+ const selects = fields.filter((field) => selected.fields.has(field));
152
+ const sent = selects.filter((field) => given(field) && !selected.windows.has(field));
153
+ if (sent.length > 0) {
154
+ const patch = Object.create(null);
155
+ for (const field of sent) patch[field] = values[field];
156
+ yield* emit(subscriber, {
157
+ _tag: "EntityPatched",
158
+ entity: ref.entity,
159
+ id: ref.id,
160
+ values: patch,
161
+ changed: sent
162
+ });
163
+ }
164
+ const sentSet = new Set(sent);
165
+ const wanted = selects.filter((field) => !sentSet.has(field));
166
+ if (wanted.length > 0) join(Object.fromEntries(wanted.flatMap((field) => {
167
+ const window = selected.windows.get(field);
168
+ return window === void 0 ? [] : [[field, window]];
169
+ })), {}, wanted);
170
+ for (const alias of selected.fields) {
171
+ const window = selected.windows.get(alias);
172
+ const field = aliasedField(alias);
173
+ if (field === alias || window === void 0 || !fields.includes(field)) continue;
174
+ join({ [field]: window }, { [field]: alias }, [field]);
175
+ }
176
+ }
177
+ const gone = /* @__PURE__ */ new Set();
178
+ const read = (principal, { windows, renames, entries: group }) => Effect.gen(function* () {
179
+ const requested = [...new Set(group.flatMap((entry) => entry.fields))];
180
+ const allowed = allowedFields(source, principal, requested);
181
+ if (allowed.length === 0) return;
182
+ const allowedSet = new Set(allowed);
183
+ const record = (yield* readFiltered(source, principal, allowed, (fields) => source.read({
184
+ ids: [ref.id],
185
+ fields,
186
+ principal,
187
+ ...windowsOf(windows, allowed)
188
+ }))).find((candidate) => candidate.id === ref.id);
189
+ for (const { subscriber, fields: wanted } of group) {
190
+ if (gone.has(subscriber)) continue;
191
+ if (record === void 0) {
192
+ gone.add(subscriber);
193
+ yield* emit(subscriber, {
194
+ _tag: "EntityDeleted",
195
+ entity: ref.entity,
196
+ id: ref.id
197
+ });
198
+ continue;
199
+ }
200
+ const values = Object.create(null);
201
+ for (const field of wanted) if (allowedSet.has(field) && Object.hasOwn(record.values, field)) values[renamed(renames, field)] = record.values[field];
202
+ const changed = Object.keys(values);
203
+ if (changed.length === 0) continue;
204
+ yield* emit(subscriber, {
205
+ _tag: "EntityPatched",
206
+ entity: ref.entity,
207
+ id: ref.id,
208
+ values,
209
+ changed
210
+ });
211
+ }
212
+ });
213
+ const failures = [];
214
+ for (const { principal, byWindows } of groups.values()) for (const group of byWindows.values()) yield* read(principal, group).pipe(Effect.catch((error) => Effect.sync(() => void failures.push(error))));
215
+ if (failures.length > 0) return yield* Effect.fail(failures[0]);
216
+ });
92
217
  return {
93
218
  subscribe: ({ requirements, after, principal, maxIdsPerEntity }) => Stream.unwrap(Effect.gen(function* () {
94
219
  const over = checkIdsPerEntity(requirements, Math.max(1, maxIdsPerEntity ?? DEFAULT_MAX_IDS_PER_ENTITY));
@@ -115,79 +240,8 @@ const liveHub = (entities) => Effect.sync(() => {
115
240
  subscribers.add(subscriber);
116
241
  return Stream.fromQueue(subscriber.queue).pipe(Stream.ensuring(Effect.sync(() => void subscribers.delete(subscriber))));
117
242
  })),
118
- changed: (ref, fields) => Effect.gen(function* () {
119
- const key = `${ref.entity}:${ref.id}`;
120
- const source = sources.get(ref.entity);
121
- if (source === void 0) return;
122
- const groups = /* @__PURE__ */ new Map();
123
- for (const subscriber of subscribers) {
124
- const selected = subscriber.selected.get(key);
125
- if (selected === void 0) continue;
126
- const byWindows = groups.get(subscriber.principal) ?? /* @__PURE__ */ new Map();
127
- groups.set(subscriber.principal, byWindows);
128
- const join = (windows, renames, wanted) => {
129
- const groupKey = `${stableStringify(windows)}\u0000${stableStringify(renames)}`;
130
- const group = byWindows.get(groupKey) ?? {
131
- windows,
132
- renames,
133
- entries: []
134
- };
135
- byWindows.set(groupKey, group);
136
- group.entries.push({
137
- subscriber,
138
- fields: wanted
139
- });
140
- };
141
- const wanted = fields.filter((field) => selected.fields.has(field));
142
- if (wanted.length > 0) join(Object.fromEntries(wanted.flatMap((field) => {
143
- const window = selected.windows.get(field);
144
- return window === void 0 ? [] : [[field, window]];
145
- })), {}, wanted);
146
- for (const alias of selected.fields) {
147
- const window = selected.windows.get(alias);
148
- const field = aliasedField(alias);
149
- if (field === alias || window === void 0 || !fields.includes(field)) continue;
150
- join({ [field]: window }, { [field]: alias }, [field]);
151
- }
152
- }
153
- for (const [principal, byWindows] of groups) for (const { windows, renames, entries: group } of byWindows.values()) {
154
- const requested = [...new Set(group.flatMap((entry) => entry.fields))];
155
- const allowed = allowedFields(source, principal, requested);
156
- if (allowed.length === 0) continue;
157
- const allowedSet = new Set(allowed);
158
- const record = (yield* source.read({
159
- ids: [ref.id],
160
- fields: allowed,
161
- principal,
162
- ...windowsOf(windows, allowed)
163
- })).find((candidate) => candidate.id === ref.id);
164
- if (record === void 0) continue;
165
- for (const { subscriber, fields: wanted } of group) {
166
- const values = Object.create(null);
167
- for (const field of wanted) if (allowedSet.has(field) && Object.hasOwn(record.values, field)) values[renamed(renames, field)] = record.values[field];
168
- const changed = Object.keys(values);
169
- if (changed.length === 0) continue;
170
- yield* emit(subscriber, {
171
- _tag: "EntityPatched",
172
- entity: ref.entity,
173
- id: ref.id,
174
- values,
175
- changed
176
- });
177
- }
178
- }
179
- }),
180
- deleted: (ref) => Effect.gen(function* () {
181
- const key = `${ref.entity}:${ref.id}`;
182
- for (const subscriber of subscribers) {
183
- if (!subscriber.selected.has(key)) continue;
184
- yield* emit(subscriber, {
185
- _tag: "EntityDeleted",
186
- entity: ref.entity,
187
- id: ref.id
188
- });
189
- }
190
- }),
243
+ changed: (ref, fields, values) => refresh(ref, Option.some(fields), values),
244
+ deleted: (ref) => refresh(ref, Option.none(), void 0),
191
245
  size: Effect.sync(() => subscribers.size)
192
246
  };
193
247
  });
@@ -350,8 +404,24 @@ const pageOf = (items, window, idOf, locate) => {
350
404
  */
351
405
  const memory = (config) => {
352
406
  const authorize = config.authorize ?? {};
353
- const unknown = Object.keys(authorize).filter((name) => !config.domain.registry.entities.has(name));
354
- if (unknown.length > 0) throw new Error(`RemoteServer.memory: \`authorize\` names ${unknown.map((name) => `"${name}"`).join(", ")}, which the domain does not declare`);
407
+ const filter = config.filter ?? {};
408
+ const shared = config.shared ?? {};
409
+ for (const [option, given] of [
410
+ ["authorize", authorize],
411
+ ["filter", filter],
412
+ ["shared", shared]
413
+ ]) {
414
+ const unknown = Object.keys(given).filter((name) => !config.domain.registry.entities.has(name));
415
+ if (unknown.length > 0) throw new Error(`RemoteServer.memory: \`${option}\` names ${unknown.map((name) => `"${name}"`).join(", ")}, which the domain does not declare`);
416
+ }
417
+ for (const [name, fields] of Object.entries(shared)) {
418
+ const entity = config.domain.registry.entities.get(name);
419
+ const declared = entity.members ?? entity.fields;
420
+ const unserved = fields.filter((field) => declared !== void 0 && !Object.hasOwn(declared, field));
421
+ if (unserved.length > 0) throw new Error(`RemoteServer.memory: ${name}'s shared fields name no member: ${unserved.join(", ")}`);
422
+ }
423
+ const everyRow = () => true;
424
+ const readableFor = (principal) => config.readable === void 0 ? Effect.succeed(everyRow) : config.readable(principal, (entity, id) => Option.fromUndefinedOr(table(entity).get(id)));
355
425
  const tables = /* @__PURE__ */ new Map();
356
426
  const table = (entity) => {
357
427
  const existing = tables.get(entity);
@@ -399,57 +469,78 @@ const memory = (config) => {
399
469
  hasPrevious: page.start._tag === "Cursor"
400
470
  };
401
471
  };
402
- const entities = [...config.domain.registry.entities.keys()].map((name) => RemoteServer.entity({ name }, {
403
- ...Object.hasOwn(authorize, name) ? { authorize: authorize[name] } : {},
404
- read: ({ ids, fields, windows }) => Effect.try({
405
- try: () => ids.flatMap((id) => {
406
- const row = table(name).get(id);
407
- if (row === void 0) return [];
408
- return [{
409
- id,
410
- values: Object.fromEntries(fields.flatMap((field) => Object.hasOwn(row, field) ? [[field, valueFor(row[field], windows?.[field])]] : []))
411
- }];
412
- }),
413
- catch: (error) => new RemoteServerError({ message: error instanceof Error ? error.message : String(error) })
472
+ const relationsOf = new Map([...config.domain.registry.entities].map(([name, descriptor]) => [name, new Set(Object.entries(descriptor.fields).flatMap(([field, schema]) => relationShape(schema) === void 0 ? [] : [field]))]));
473
+ const refsShown = (readable, entity, field, value) => {
474
+ if (readable === everyRow || relationsOf.get(entity)?.has(field) !== true) return value;
475
+ const shown = (ref) => {
476
+ if (typeof ref !== "string") return true;
477
+ const { entity: target, id } = refParts(ref);
478
+ const row = table(target).get(id);
479
+ return row !== void 0 && readable(target, row);
480
+ };
481
+ if (Array.isArray(value)) return value.filter(shown);
482
+ return shown(value) ? value : null;
483
+ };
484
+ const visible = config.readable === void 0 ? {} : { visible: config.readable };
485
+ const entities = [...config.domain.registry.entities.keys()].map((name) => ({
486
+ ...visible,
487
+ ...RemoteServer.entity({ name }, {
488
+ ...Object.hasOwn(authorize, name) ? { authorize: authorize[name] } : {},
489
+ ...Object.hasOwn(filter, name) ? { filter: filter[name] } : {},
490
+ ...Object.hasOwn(shared, name) ? { shared: shared[name] } : {},
491
+ read: ({ ids, fields, windows, principal }) => Effect.flatMap(readableFor(principal), (readable) => Effect.try({
492
+ try: () => ids.flatMap((id) => {
493
+ const row = table(name).get(id);
494
+ if (row === void 0 || !readable(name, row)) return [];
495
+ return [{
496
+ id,
497
+ values: Object.fromEntries(fields.flatMap((field) => Object.hasOwn(row, field) ? [[field, valueFor(refsShown(readable, name, field, row[field]), windows?.[field])]] : []))
498
+ }];
499
+ }),
500
+ catch: (error) => new RemoteServerError({ message: error instanceof Error ? error.message : String(error) })
501
+ }))
414
502
  })
415
503
  }));
416
504
  const given = new Set((config.queries ?? []).map((source) => source.query));
417
505
  const bodiless = [...config.domain.registry.queries.values()].filter((query) => query.body === void 0 && !given.has(query.name));
418
506
  if (bodiless.length > 0) throw new Error(`RemoteServer.memory: ${bodiless.map((query) => `"${query.name}"`).join(", ")} ${bodiless.length === 1 ? "has" : "have"} no body to run. Declare ${bodiless.length === 1 ? "it" : "them"} with Query.define, or give a source in \`queries\`.`);
419
- const queries = [...config.queries ?? [], ...[...config.domain.registry.queries.values()].filter((query) => !given.has(query.name)).map((query) => RemoteServer.query(query, ({ input, window }) => Effect.try({
420
- try: () => {
421
- const body = query.body;
422
- const encoded = Schema.encodeSync(query.Input)(input);
423
- const entity = body.entity.name;
424
- const rows = store.rows(entity);
425
- const matched = evaluate$1(body, encoded, rows);
426
- const locate = (cursor) => {
427
- const row = rows.find((candidate) => String(candidate.id) === cursor);
428
- if (row === void 0) throw new Error(`Cursor "${cursor}" names a row that no longer exists`);
429
- return {
430
- index: evaluate$1({
431
- ...body,
432
- where: []
433
- }, encoded, [...matched, row]).indexOf(row),
434
- exact: false
435
- };
436
- };
437
- const page = pageOf(matched, window, (row) => String(row.id), locate);
438
- return {
439
- edges: page.items.map((row) => {
440
- const id = String(row.id);
507
+ const queries = [...config.queries ?? [], ...[...config.domain.registry.queries.values()].filter((query) => !given.has(query.name)).map((query) => ({
508
+ ...visible,
509
+ ...RemoteServer.query(query, ({ input, window, principal }) => Effect.flatMap(readableFor(principal), (readable) => Effect.try({
510
+ try: () => {
511
+ const body = query.body;
512
+ const encoded = Schema.encodeSync(query.Input)(input);
513
+ const entity = body.entity.name;
514
+ const rows = store.rows(entity).filter((row) => readable(entity, row));
515
+ const matched = evaluate$1(body, encoded, rows);
516
+ const locate = (cursor) => {
517
+ const row = rows.find((candidate) => String(candidate.id) === cursor);
518
+ if (row === void 0) throw new Error(`Cursor "${cursor}" names a row that no longer exists`);
441
519
  return {
442
- entity,
443
- id,
444
- key: entityKey(entity, id)
520
+ index: evaluate$1({
521
+ ...body,
522
+ where: []
523
+ }, encoded, [...matched, row]).indexOf(row),
524
+ exact: false
445
525
  };
446
- }),
447
- start: page.start,
448
- end: page.end
449
- };
450
- },
451
- catch: (error) => new RemoteServerError({ message: error instanceof Error ? error.message : String(error) })
452
- })))];
526
+ };
527
+ const page = pageOf(matched, window, (row) => String(row.id), locate);
528
+ return {
529
+ edges: page.items.map((row) => {
530
+ const id = String(row.id);
531
+ return {
532
+ entity,
533
+ id,
534
+ key: entityKey(entity, id)
535
+ };
536
+ }),
537
+ start: page.start,
538
+ end: page.end
539
+ };
540
+ },
541
+ catch: (error) => new RemoteServerError({ message: error instanceof Error ? error.message : String(error) })
542
+ })))
543
+ }))];
453
544
  const server = RemoteServer.make({
454
545
  entities,
455
546
  queries,
@@ -461,6 +552,20 @@ const memory = (config) => {
461
552
  layer: Remote.clientLayer(RemoteServer.handlers(server, config.principal))
462
553
  };
463
554
  };
555
+ /**
556
+ * A Source's refusal as the client receives it: encoded by the mutation's own
557
+ * `Refusal`. A refusal made for another mutation, or one the mutation does not
558
+ * declare, is this side's bug, and says so without the value.
559
+ */
560
+ const refusalError = (Refusal, mutation, refused) => Effect.gen(function* () {
561
+ const invalid = new RemoteMutationError({ message: "Invalid mutation refusal" });
562
+ if (refused.mutation !== mutation) return yield* invalid;
563
+ const encoded = yield* Schema.encodeUnknownEffect(Refusal)(refused.refusal).pipe(Effect.mapError(() => invalid));
564
+ return yield* new RemoteMutationError({
565
+ message: refused.message,
566
+ refusal: encoded
567
+ });
568
+ });
464
569
  const RemoteServer = {
465
570
  /** A backend held in memory, for a first run, a test or a demo. See `memory`. */
466
571
  memory,
@@ -476,19 +581,29 @@ const RemoteServer = {
476
581
  * `name` and `fields`, those fields. A request for anything else never
477
582
  * reaches `read` or `authorize`. Given only a `name`, every field passes.
478
583
  */
479
- entity: (entity, options) => ({
480
- entity: entity.name,
481
- ...(entity.members ?? entity.fields) === void 0 ? {} : { fields: new Set(Object.keys(entity.members ?? entity.fields)) },
482
- read: options.read,
483
- ...options.authorize === void 0 ? {} : { authorize: options.authorize }
484
- }),
584
+ entity: (entity, options) => {
585
+ const declared = entity.members ?? entity.fields;
586
+ const fields = declared === void 0 ? void 0 : new Set(Object.keys(declared));
587
+ const unserved = (options.shared ?? []).filter((field) => fields !== void 0 && !fields.has(field));
588
+ if (unserved.length > 0) throw new Error(`[foldkit-remote-server] ${entity.name}'s shared fields name no member: ${unserved.join(", ")}`);
589
+ return {
590
+ entity: entity.name,
591
+ ...fields === void 0 ? {} : { fields },
592
+ read: options.read,
593
+ ...options.authorize === void 0 ? {} : { authorize: options.authorize },
594
+ ...options.filter === void 0 ? {} : { filter: options.filter },
595
+ ...options.shared === void 0 ? {} : { shared: new Set(options.shared) }
596
+ };
597
+ },
485
598
  mutation: (mutation, run) => ({
486
599
  mutation: mutation.name,
487
600
  Input: mutation.Input,
488
601
  Output: mutation.Output,
602
+ Refusal: mutation.Refusal,
489
603
  run: (context) => run({
490
604
  input: context.input,
491
- principal: context.principal
605
+ principal: context.principal,
606
+ requestId: context.requestId
492
607
  }).pipe(Effect.map((outcome) => ({
493
608
  output: outcome.output,
494
609
  entities: outcome.entities ?? [],
@@ -496,6 +611,127 @@ const RemoteServer = {
496
611
  deleted: outcome.deleted ?? []
497
612
  })))
498
613
  }),
614
+ /**
615
+ * A refusal of `mutation`, as a value of its declared `Refusal`: fail a
616
+ * Source with it (`yield* RemoteServer.refuse(SavePost, { _tag: 'Field', ... })`)
617
+ * and the client reads it, decoded, with `Data.refusal`. `message` is what a
618
+ * person reads, beside it.
619
+ */
620
+ refuse: (mutation, refusal, message = `Mutation ${mutation.name} was refused`) => new MutationRefused({
621
+ mutation: mutation.name,
622
+ refusal,
623
+ message
624
+ }),
625
+ /**
626
+ * A refusal of who is asking: fail a Source with it
627
+ * (`yield* RemoteServer.forbid()`) and the write never runs. `reason`, when
628
+ * given, is what the person who asked reads; without it the refusal says
629
+ * nothing of why. `answer` sends it as a 403, and the client's mutation
630
+ * fails with `_tag: 'Forbidden'`.
631
+ */
632
+ forbid: (reason) => new RemoteForbidden({
633
+ message: reason ?? "Forbidden",
634
+ ...reason === void 0 ? {} : { reason }
635
+ }),
636
+ /**
637
+ * The Source of a mutation that is a declared `Write`, with no handler: the
638
+ * input bound to the write lands through `writer`, and the row as written
639
+ * answers as a patch (a deletion as `deleted`). An update writes only the
640
+ * keys the client named, when it named some, and fails for a row that is not
641
+ * there; an insert of an id already holding what it writes (a retry)
642
+ * answers with that row, and of one holding anything else fails; a delete of
643
+ * a row already gone succeeds. A row that moved past the revision the write
644
+ * `expect`s is refused as a conflict.
645
+ */
646
+ write: (mutation, writer) => {
647
+ const { write } = mutation;
648
+ if (write.input.entity.name !== writer.entity) throw new Error(`[foldkit-remote-server] write "${mutation.name}" writes ${write.input.entity.name}, but its writer is for ${writer.entity}`);
649
+ return {
650
+ mutation: mutation.name,
651
+ writes: {
652
+ entity: writer.entity,
653
+ writer
654
+ },
655
+ Input: mutation.Input,
656
+ Output: mutation.Output,
657
+ Refusal: mutation.Refusal,
658
+ run: ({ input, principal, keys }) => {
659
+ const given = input;
660
+ const expect = Write.expected(write, given);
661
+ const conflict = (bound) => RemoteServer.refuse(mutation, { _tag: "Conflict" }, `${bound.entity} ${bound.id} changed since it was read`);
662
+ const answered = (bound, values) => {
663
+ const read = writer.read;
664
+ const shown = read === void 0 ? Effect.succeed(Option.some(values)) : read({
665
+ id: bound.id,
666
+ fields: Object.keys(values),
667
+ principal
668
+ });
669
+ return Effect.map(shown, Option.match({
670
+ onNone: () => ({
671
+ output: {},
672
+ entities: [],
673
+ connections: [],
674
+ deleted: [{
675
+ entity: bound.entity,
676
+ id: bound.id
677
+ }]
678
+ }),
679
+ onSome: (seen) => ({
680
+ output: {},
681
+ entities: [{
682
+ entity: bound.entity,
683
+ id: bound.id,
684
+ values: seen
685
+ }],
686
+ connections: [],
687
+ deleted: []
688
+ })
689
+ }));
690
+ };
691
+ return Match.value(write).pipe(Match.tagsExhaustive({
692
+ Update: () => Effect.gen(function* () {
693
+ const bound = Write.bind(write, given, keys);
694
+ const written = yield* writer.update({
695
+ id: bound.id,
696
+ values: bound.values,
697
+ links: bound.links,
698
+ expect,
699
+ principal
700
+ });
701
+ if (Option.isSome(written)) return yield* answered(bound, written.value);
702
+ return yield* Option.isSome(expect) ? Effect.fail(conflict(bound)) : Effect.fail(new RemoteServerError({ message: `No ${bound.entity} ${bound.id} to update` }));
703
+ }),
704
+ Insert: () => Effect.gen(function* () {
705
+ const bound = Write.bind(write, given);
706
+ const row = yield* writer.insert({
707
+ id: bound.id,
708
+ values: bound.values,
709
+ links: bound.links,
710
+ principal
711
+ });
712
+ return yield* answered(bound, row);
713
+ }),
714
+ Delete: () => Effect.gen(function* () {
715
+ const bound = Write.bind(write, given);
716
+ if ((yield* writer.delete({
717
+ id: bound.id,
718
+ expect,
719
+ principal
720
+ })) === "moved") return yield* Effect.fail(conflict(bound));
721
+ return {
722
+ output: {},
723
+ entities: [],
724
+ connections: [],
725
+ deleted: [{
726
+ entity: bound.entity,
727
+ id: bound.id
728
+ }]
729
+ };
730
+ })
731
+ }));
732
+ }
733
+ };
734
+ },
499
735
  query: (query, run) => ({
500
736
  query: query.name,
501
737
  Input: query.Input,
@@ -512,12 +748,12 @@ const RemoteServer = {
512
748
  subscribe: options.subscribe
513
749
  }),
514
750
  /**
515
- * A `LiveHub` over entity sources. Pass it to `handlers` as `live`, then
516
- * call `hub.changed(ref, fields)` from wherever the data changes (a mutation
517
- * source, a database trigger); each subscriber that selects any of those
518
- * fields receives them, re-read through the entity source under its own
519
- * principal. It needs only the entity sources, so the mutation sources that
520
- * signal it can be built after it.
751
+ * A `LiveHub` over entity sources. Pass it to `handlers` as `live`, and every
752
+ * mutation's answered patches and deletions are published to it; call
753
+ * `hub.changed(ref, fields)` yourself only for a write that is not a
754
+ * mutation (a database trigger, a job). Each subscriber that selects any of
755
+ * those fields receives them, re-read through the entity source under its
756
+ * own principal.
521
757
  */
522
758
  liveHub,
523
759
  make: (config) => ({
@@ -540,12 +776,6 @@ const RemoteServer = {
540
776
  assertDeclared("mutation", domain.registry.mutations, server.mutations.keys());
541
777
  },
542
778
  /**
543
- * Compiles the server into the `Read`/`Mutate` RPC handlers. `principal` is
544
- * resolved outside (authentication middleware in a later phase); unknown
545
- * entities, entities with no allowed fields, and unknown mutations return an
546
- * error or nothing rather than leaking existence.
547
- */
548
- /**
549
779
  * Reads entity requirements through the entity sources, level by level,
550
780
  * following relations as `FoldkitRemoteRead` does. Shared by the read
551
781
  * handler and the query handler's payload: a query page's items are just
@@ -606,13 +836,12 @@ const RemoteServer = {
606
836
  for (const [id, asked] of ids) settle(name, id, [...asked].filter((field) => !allowedSet.has(field)).map((field) => renamed(renames, field)));
607
837
  if (allowed.length === 0) continue;
608
838
  const windows = windowsOf(slice.windows, allowed);
609
- const records = [];
610
- for (let start = 0; start < idList.length; start += maxIds) records.push(...yield* source.read({
611
- ids: idList.slice(start, start + maxIds),
612
- fields: allowed,
839
+ const records = yield* readFiltered(source, principal, allowed, (fields) => Effect.map(Effect.forEach(Array.from({ length: Math.ceil(idList.length / maxIds) }, (_, chunk) => idList.slice(chunk * maxIds, (chunk + 1) * maxIds)), (chunk) => source.read({
840
+ ids: chunk,
841
+ fields,
613
842
  principal,
614
843
  ...windows
615
- }).pipe(Effect.catchTag("RemoteServerError", (error) => Effect.fail(new RemoteReadError({ message: error.message })))));
844
+ })), (chunks) => chunks.flat())).pipe(Effect.catchTag("RemoteServerError", (error) => Effect.fail(new RemoteReadError({ message: error.message }))));
616
845
  for (const record of records) {
617
846
  const values = Object.create(null);
618
847
  const omitted = [];
@@ -658,8 +887,9 @@ const RemoteServer = {
658
887
  * worker or a server in the page calls with the body it received, parsed.
659
888
  * The request and its payload are decoded by the protocol's own schemas
660
889
  * before a handler sees them, so an operation name is one of Remote's three
661
- * and nothing else. A body that is not a request is a 400; a handler's
662
- * failure a 500 with its message; a defect a 500 that says nothing of it.
890
+ * and nothing else. A body that is not a request is a 400; a refusal of who
891
+ * is asking a 403; a handler's failure a 500 with its message; a defect a
892
+ * 500 that says nothing of it.
663
893
  * `Remote.json` and `Remote.http` are the other end.
664
894
  */
665
895
  answer: (handlers, body) => {
@@ -674,6 +904,21 @@ const RemoteServer = {
674
904
  })), Effect.catchTag("SchemaError", (error) => Effect.succeed({
675
905
  status: 400,
676
906
  body: { error: error.message }
907
+ })), Effect.catchTag("Forbidden", (error) => Effect.succeed({
908
+ status: 403,
909
+ body: {
910
+ error: error.message,
911
+ forbidden: error.reason === void 0 ? {} : { reason: error.reason }
912
+ }
913
+ })), Effect.catchTag("RemoteMutationError", (error) => Effect.succeed(error.refusal === void 0 ? {
914
+ status: 500,
915
+ body: { error: error.message }
916
+ } : {
917
+ status: 422,
918
+ body: {
919
+ error: error.message,
920
+ refusal: error.refusal
921
+ }
677
922
  })), Effect.catch((error) => Effect.succeed({
678
923
  status: 500,
679
924
  body: { error: error.message }
@@ -682,99 +927,125 @@ const RemoteServer = {
682
927
  body: { error: "Internal error" }
683
928
  })));
684
929
  },
685
- handlers: (server, principal, options = {}) => ({
686
- FoldkitRemoteRead: Effect.fn("RemoteServer.FoldkitRemoteRead")(function* (payload) {
687
- const mismatch = protocolMismatch(payload.version);
688
- if (mismatch !== void 0) return yield* mismatch;
689
- return yield* RemoteServer.readHelper(server, principal, options, payload.requests);
690
- }),
691
- FoldkitRemoteMutate: Effect.fn("RemoteServer.FoldkitRemoteMutate")(function* (payload) {
692
- const source = server.mutations.get(payload.mutation);
693
- if (source === void 0) return yield* new RemoteMutationError({ message: `Unknown mutation: ${payload.mutation}` });
694
- const input = yield* Schema.decodeUnknownEffect(source.Input)(payload.input).pipe(Effect.catchTag("SchemaError", () => Effect.fail(new RemoteMutationError({ message: "Invalid mutation input" }))));
695
- const outcome = yield* source.run({
696
- input,
697
- principal
698
- }).pipe(Effect.catchTag("RemoteServerError", (error) => Effect.fail(new RemoteMutationError({ message: error.message }))));
699
- return {
700
- output: yield* Schema.encodeUnknownEffect(source.Output)(outcome.output).pipe(Effect.catchTag("SchemaError", () => Effect.fail(new RemoteMutationError({ message: "Invalid mutation output" })))),
701
- entities: outcome.entities.map((patch) => ({
702
- entity: patch.entity,
703
- id: patch.id,
704
- values: patch.values
705
- })),
706
- connections: outcome.connections,
707
- deleted: outcome.deleted.map((gone) => ({
708
- entity: gone.entity,
709
- id: gone.id
710
- }))
711
- };
712
- }),
713
- FoldkitRemoteQuery: Effect.fn("RemoteServer.FoldkitRemoteQuery")(function* (payload) {
714
- const source = server.queries.get(payload.query);
715
- if (source === void 0) return yield* new RemoteQueryError({ message: `Unknown query: ${payload.query}` });
716
- const input = yield* Schema.decodeUnknownEffect(source.Input)(payload.input).pipe(Effect.catchTag("SchemaError", () => Effect.fail(new RemoteQueryError({ message: "Invalid query input" }))));
717
- const select = payload.select;
718
- if (select !== void 0) {
719
- const paged = checkPagesPerRelation([select]);
720
- if (paged !== void 0) return yield* new RemoteQueryError({ message: `Too many pages of "${paged}" in one query select` });
930
+ /**
931
+ * Compiles the server into Remote's RPC handlers, answering as `principal`:
932
+ * a value, or a Context key (`G.Principal`) read on each call, which
933
+ * authentication provides per request. Unknown entities, entities with no
934
+ * allowed fields, and unknown mutations return an error or nothing rather
935
+ * than leaking existence.
936
+ */
937
+ handlers: (server, principal, options = {}) => {
938
+ const asking = Context.isKey(principal) ? principal : Effect.succeed(principal);
939
+ return {
940
+ FoldkitRemoteRead: Effect.fn("RemoteServer.FoldkitRemoteRead")(function* (payload) {
941
+ const mismatch = protocolMismatch(payload.version);
942
+ if (mismatch !== void 0) return yield* mismatch;
943
+ const caller = yield* asking;
944
+ return yield* RemoteServer.readHelper(server, caller, options, payload.requests);
945
+ }),
946
+ FoldkitRemoteMutate: Effect.fn("RemoteServer.FoldkitRemoteMutate")(function* (payload) {
947
+ const source = server.mutations.get(payload.mutation);
948
+ if (source === void 0) return yield* new RemoteMutationError({ message: `Unknown mutation: ${payload.mutation}` });
949
+ const input = yield* Schema.decodeUnknownEffect(source.Input)(payload.input).pipe(Effect.catchTag("SchemaError", () => Effect.fail(new RemoteMutationError({ message: "Invalid mutation input" }))));
950
+ const caller = yield* asking;
951
+ const outcome = yield* source.run({
952
+ input,
953
+ principal: caller,
954
+ requestId: payload.requestId,
955
+ keys: payload.keys
956
+ }).pipe(Effect.catchTag("RemoteServerError", (error) => Effect.fail(new RemoteMutationError({ message: error.message }))), Effect.catchTag("MutationRefused", (refused) => refusalError(source.Refusal, payload.mutation, refused)));
957
+ const output = yield* Schema.encodeUnknownEffect(source.Output)(outcome.output).pipe(Effect.catchTag("SchemaError", () => Effect.fail(new RemoteMutationError({ message: "Invalid mutation output" }))));
958
+ const hub = options.live;
959
+ if (hub !== void 0) {
960
+ const stored = source.writes !== void 0;
961
+ yield* Effect.forEach(outcome.entities, (patch) => hub.changed({
962
+ entity: patch.entity,
963
+ id: patch.id
964
+ }, Object.keys(patch.values), stored ? patch.values : void 0)).pipe(Effect.andThen(Effect.forEach(outcome.deleted, (gone) => hub.deleted(gone))), Effect.catchCause((cause) => Effect.logWarning("RemoteServer: a mutation committed but its live publish failed", cause)));
965
+ }
966
+ return {
967
+ output,
968
+ entities: outcome.entities.map((patch) => ({
969
+ entity: patch.entity,
970
+ id: patch.id,
971
+ values: patch.values
972
+ })),
973
+ connections: outcome.connections,
974
+ deleted: outcome.deleted.map((gone) => ({
975
+ entity: gone.entity,
976
+ id: gone.id
977
+ }))
978
+ };
979
+ }),
980
+ FoldkitRemoteQuery: Effect.fn("RemoteServer.FoldkitRemoteQuery")(function* (payload) {
981
+ const source = server.queries.get(payload.query);
982
+ if (source === void 0) return yield* new RemoteQueryError({ message: `Unknown query: ${payload.query}` });
983
+ const input = yield* Schema.decodeUnknownEffect(source.Input)(payload.input).pipe(Effect.catchTag("SchemaError", () => Effect.fail(new RemoteQueryError({ message: "Invalid query input" }))));
984
+ const select = payload.select;
985
+ if (select !== void 0) {
986
+ const paged = checkPagesPerRelation([select]);
987
+ if (paged !== void 0) return yield* new RemoteQueryError({ message: `Too many pages of "${paged}" in one query select` });
988
+ }
989
+ const caller = yield* asking;
990
+ const page = yield* source.run({
991
+ input,
992
+ window: payload.window,
993
+ principal: caller,
994
+ ...select === void 0 ? {} : { select }
995
+ }).pipe(Effect.catchTag("RemoteServerError", (error) => Effect.fail(new RemoteQueryError({ message: error.message }))));
996
+ if (select === void 0) return {
997
+ edges: page.edges,
998
+ start: page.start,
999
+ end: page.end
1000
+ };
1001
+ const requirements = page.edges.flatMap((edge) => edge.entity === select.entity ? [{
1002
+ entity: select.entity,
1003
+ id: edge.id,
1004
+ fields: [...select.fields],
1005
+ ...select.windows === void 0 ? {} : { windows: select.windows },
1006
+ ...select.relations === void 0 ? {} : { relations: select.relations }
1007
+ }] : []);
1008
+ if (requirements.length === 0) return {
1009
+ edges: page.edges,
1010
+ start: page.start,
1011
+ end: page.end,
1012
+ entities: [],
1013
+ settled: []
1014
+ };
1015
+ const read = yield* RemoteServer.readHelper(server, caller, options, requirements).pipe(Effect.catchTag("RemoteReadError", (error) => Effect.fail(new RemoteQueryError({ message: error.message }))));
1016
+ return {
1017
+ edges: page.edges,
1018
+ start: page.start,
1019
+ end: page.end,
1020
+ ...read
1021
+ };
1022
+ }),
1023
+ FoldkitRemoteLive: (payload) => {
1024
+ const mismatch = protocolMismatch(payload.version);
1025
+ if (mismatch !== void 0) return Stream.fail(mismatch);
1026
+ return Stream.unwrap(Effect.map(asking, (caller) => {
1027
+ const streams = [...new Set(payload.requirements.map((request) => request.entity))].flatMap((entity) => {
1028
+ const source = server.live.get(entity);
1029
+ if (source === void 0) return [];
1030
+ return [source.subscribe({
1031
+ requirements: payload.requirements.filter((request) => request.entity === entity),
1032
+ after: payload.after,
1033
+ principal: caller
1034
+ })];
1035
+ });
1036
+ if (options.live !== void 0) streams.push(options.live.subscribe({
1037
+ requirements: payload.requirements,
1038
+ after: payload.after,
1039
+ principal: caller,
1040
+ maxIdsPerEntity: options.maxIdsPerEntity
1041
+ }));
1042
+ return Stream.mergeAll(streams, { concurrency: "unbounded" }).pipe(Stream.mapError((error) => new RemoteLiveError({ message: error.message })));
1043
+ }));
721
1044
  }
722
- const page = yield* source.run({
723
- input,
724
- window: payload.window,
725
- principal,
726
- ...select === void 0 ? {} : { select }
727
- }).pipe(Effect.catchTag("RemoteServerError", (error) => Effect.fail(new RemoteQueryError({ message: error.message }))));
728
- if (select === void 0) return {
729
- edges: page.edges,
730
- start: page.start,
731
- end: page.end
732
- };
733
- const requirements = page.edges.flatMap((edge) => edge.entity === select.entity ? [{
734
- entity: select.entity,
735
- id: edge.id,
736
- fields: [...select.fields],
737
- ...select.windows === void 0 ? {} : { windows: select.windows },
738
- ...select.relations === void 0 ? {} : { relations: select.relations }
739
- }] : []);
740
- if (requirements.length === 0) return {
741
- edges: page.edges,
742
- start: page.start,
743
- end: page.end,
744
- entities: [],
745
- settled: []
746
- };
747
- const read = yield* RemoteServer.readHelper(server, principal, options, requirements).pipe(Effect.catchTag("RemoteReadError", (error) => Effect.fail(new RemoteQueryError({ message: error.message }))));
748
- return {
749
- edges: page.edges,
750
- start: page.start,
751
- end: page.end,
752
- ...read
753
- };
754
- }),
755
- FoldkitRemoteLive: (payload) => {
756
- const mismatch = protocolMismatch(payload.version);
757
- if (mismatch !== void 0) return Stream.fail(mismatch);
758
- const streams = [...new Set(payload.requirements.map((request) => request.entity))].flatMap((entity) => {
759
- const source = server.live.get(entity);
760
- if (source === void 0) return [];
761
- return [source.subscribe({
762
- requirements: payload.requirements.filter((request) => request.entity === entity),
763
- after: payload.after,
764
- principal
765
- })];
766
- });
767
- if (options.live !== void 0) streams.push(options.live.subscribe({
768
- requirements: payload.requirements,
769
- after: payload.after,
770
- principal,
771
- maxIdsPerEntity: options.maxIdsPerEntity
772
- }));
773
- return Stream.mergeAll(streams, { concurrency: "unbounded" }).pipe(Stream.mapError((error) => new RemoteLiveError({ message: error.message })));
774
- }
775
- })
1045
+ };
1046
+ }
776
1047
  };
777
1048
  //#endregion
778
- export { QueryEvaluateError, RemoteServer, RemoteServerError, assertSupported, evaluate, supported };
1049
+ export { MutationRefused, QueryEvaluateError, RemoteServer, RemoteServerError, assertSupported, evaluate, supported };
779
1050
 
780
1051
  //# sourceMappingURL=index.mjs.map