foldkit-remote-server 0.17.0 → 0.19.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 +442 -149
- package/dist/fetch.d.mts +30 -3
- package/dist/fetch.d.mts.map +1 -1
- package/dist/fetch.mjs +52 -16
- package/dist/fetch.mjs.map +1 -1
- package/dist/index-BnaRbvjr.d.mts +937 -0
- package/dist/index-BnaRbvjr.d.mts.map +1 -0
- package/dist/index.d.mts +2 -638
- package/dist/index.mjs +1 -1
- package/dist/{src-ErnDxcWe.mjs → src-ZV9pARkU.mjs} +478 -59
- package/dist/src-ZV9pARkU.mjs.map +1 -0
- package/package.json +8 -8
- package/dist/index.d.mts.map +0 -1
- package/dist/src-ErnDxcWe.mjs.map +0 -1
|
@@ -0,0 +1,937 @@
|
|
|
1
|
+
import { Cause, Context, Data, Duration, Effect, Layer, Option, Schema, Stream } from "effect";
|
|
2
|
+
import { AnyQuery, AnyWrite, Computation, EntityRef, ExprContext, MemoryOperators, QueryEvaluateError, Row, WriteAssignment, assertSupported as assertSupported$1, evaluate as evaluate$1, supported } from "foldkit-entity";
|
|
3
|
+
import { Boundary, ConnectionChangeSchema, ConnectionIdentity, ConnectionSpec, Diagnostic, LiveChange, MutationDescriptor, NormalizedPatch, QueryDescriptor, QueryWindow, RelationRequirement, RemoteClient, RemoteDescriptor, RemoteForbidden, RemoteJsonAnswer, RemoteReadError, RemoteRpcClient, RemoteUnauthenticated, Requirement } from "foldkit-remote";
|
|
4
|
+
/** A failure on this side, answered "Internal error"; the caller is told nothing of it. */
|
|
5
|
+
interface ServerDefect extends Diagnostic {
|
|
6
|
+
readonly _tag: 'ServerDefect';
|
|
7
|
+
readonly cause: Cause.Cause<unknown>;
|
|
8
|
+
}
|
|
9
|
+
/** A mutation that committed, answered without the read of the rows it names: the client reads them again. */
|
|
10
|
+
interface AnswerUnread extends Diagnostic {
|
|
11
|
+
readonly _tag: 'AnswerUnread';
|
|
12
|
+
readonly mutation: string;
|
|
13
|
+
/** Why the read failed. */
|
|
14
|
+
readonly reason: string;
|
|
15
|
+
}
|
|
16
|
+
/** A mutation that committed, whose live publish failed: live subscribers do not hear it. */
|
|
17
|
+
interface PublishFailed extends Diagnostic {
|
|
18
|
+
readonly _tag: 'PublishFailed';
|
|
19
|
+
readonly mutation: string;
|
|
20
|
+
readonly cause: Cause.Cause<unknown>;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* A write sent at a time further from this server's clock than its
|
|
24
|
+
* `clockSkew`: the server wrote its own time instead, so what the client
|
|
25
|
+
* predicted of it is off until the answer lands.
|
|
26
|
+
*/
|
|
27
|
+
interface ClockSkewed extends Diagnostic {
|
|
28
|
+
readonly _tag: 'ClockSkewed';
|
|
29
|
+
readonly mutation: string;
|
|
30
|
+
/** The client's time, in milliseconds since the epoch. */
|
|
31
|
+
readonly sent: number;
|
|
32
|
+
/** This server's clock when it read the write, which it wrote instead. */
|
|
33
|
+
readonly own: number;
|
|
34
|
+
/** The bound, in milliseconds. */
|
|
35
|
+
readonly bound: number;
|
|
36
|
+
}
|
|
37
|
+
/** Every diagnostic a Remote server reports. */
|
|
38
|
+
type RemoteServerDiagnostic = ServerDefect | AnswerUnread | PublishFailed | ClockSkewed;
|
|
39
|
+
declare const RemoteServerError_base: Schema.Class<RemoteServerError, Schema.TaggedStruct<"RemoteServerError", {
|
|
40
|
+
readonly message: Schema.String;
|
|
41
|
+
}>, Cause.YieldableError>;
|
|
42
|
+
declare class RemoteServerError extends RemoteServerError_base {}
|
|
43
|
+
declare const RemoteUnmet_base: Schema.Class<RemoteUnmet, Schema.TaggedStruct<"RemoteUnmet", {
|
|
44
|
+
readonly message: Schema.String;
|
|
45
|
+
}>, Cause.YieldableError>;
|
|
46
|
+
/**
|
|
47
|
+
* A writer's word that the row does not hold what the write's `when` asks of
|
|
48
|
+
* it, where the write would commit: `RemoteServer.write` answers it as the
|
|
49
|
+
* mutation's `Unmet` refusal.
|
|
50
|
+
*/
|
|
51
|
+
declare class RemoteUnmet extends RemoteUnmet_base {}
|
|
52
|
+
declare const RemoteTaken_base: Schema.Class<RemoteTaken, Schema.TaggedStruct<"RemoteTaken", {
|
|
53
|
+
readonly message: Schema.String;
|
|
54
|
+
}>, Cause.YieldableError>;
|
|
55
|
+
/**
|
|
56
|
+
* A writer's word that a row already holds the id an insert names, and its
|
|
57
|
+
* ledger records no insert of this operation that made it: `RemoteServer.write`
|
|
58
|
+
* answers it as the mutation's `Taken` refusal. It says nothing of the row,
|
|
59
|
+
* which may be hidden from whoever asked.
|
|
60
|
+
*/
|
|
61
|
+
declare class RemoteTaken extends RemoteTaken_base {}
|
|
62
|
+
declare const RemoteInvalid_base: Schema.Class<RemoteInvalid, Schema.TaggedStruct<"RemoteInvalid", {
|
|
63
|
+
readonly message: Schema.String;
|
|
64
|
+
readonly rule: Schema.Option<Schema.String>;
|
|
65
|
+
readonly path: Schema.$Array<Schema.String>;
|
|
66
|
+
}>, Cause.YieldableError>;
|
|
67
|
+
/**
|
|
68
|
+
* A writer's word that the row a write would leave breaks one of its Entity's
|
|
69
|
+
* invariants: `RemoteServer.write` answers it as the mutation's `Invalid`
|
|
70
|
+
* refusal. `rule` and `path` are none and empty when saying them would tell
|
|
71
|
+
* the caller what a member hidden from them holds.
|
|
72
|
+
*/
|
|
73
|
+
declare class RemoteInvalid extends RemoteInvalid_base {}
|
|
74
|
+
/** A write's precondition as a writer is handed it: the body, and the input encoded. */
|
|
75
|
+
interface WriteWhen {
|
|
76
|
+
readonly body: AnyQuery;
|
|
77
|
+
readonly input: Readonly<Record<string, unknown>>;
|
|
78
|
+
}
|
|
79
|
+
declare const MutationRefused_base: Schema.Class<MutationRefused, Schema.TaggedStruct<"MutationRefused", {
|
|
80
|
+
/** The mutation the refusal was made for: a Source refusing as another is a bug. */
|
|
81
|
+
readonly mutation: Schema.String;
|
|
82
|
+
readonly refusal: Schema.Unknown;
|
|
83
|
+
/** What a person reads: the error's message beside the refusal. */
|
|
84
|
+
readonly message: Schema.String;
|
|
85
|
+
}>, Cause.YieldableError>;
|
|
86
|
+
/**
|
|
87
|
+
* A mutation Source's refusal, as the value its descriptor's `Refusal`
|
|
88
|
+
* declares: made with `RemoteServer.refuse`, which checks the value's type
|
|
89
|
+
* against the mutation, and sent to the client encoded, beside a message.
|
|
90
|
+
*/
|
|
91
|
+
declare class MutationRefused extends MutationRefused_base {}
|
|
92
|
+
interface EntityRecord {
|
|
93
|
+
readonly id: string;
|
|
94
|
+
readonly values: Readonly<Record<string, unknown>>;
|
|
95
|
+
}
|
|
96
|
+
interface EntitySourceContext<P> {
|
|
97
|
+
readonly ids: readonly string[];
|
|
98
|
+
readonly fields: readonly string[];
|
|
99
|
+
/** A pagination window per requested relation field. */
|
|
100
|
+
readonly windows?: Readonly<Record<string, QueryWindow>> | undefined;
|
|
101
|
+
readonly principal: P;
|
|
102
|
+
/**
|
|
103
|
+
* Who asks, as a row: the server's `viewer` of the principal, none for a
|
|
104
|
+
* visitor. Given by the server a source is mounted in; a read made outside
|
|
105
|
+
* one (a test, a tool) gives none, and a source refuses it a member that
|
|
106
|
+
* depends on who reads it.
|
|
107
|
+
*/
|
|
108
|
+
readonly viewer?: Option.Option<EntityRef> | undefined;
|
|
109
|
+
}
|
|
110
|
+
interface EntitySource<P, R = never> {
|
|
111
|
+
readonly entity: string;
|
|
112
|
+
/** The fields the entity declares; a request for any other never reaches `read`. */
|
|
113
|
+
readonly fields?: ReadonlySet<string> | undefined;
|
|
114
|
+
readonly read: (context: EntitySourceContext<P>) => Effect.Effect<ReadonlyArray<EntityRecord>, RemoteServerError, R>;
|
|
115
|
+
/** Returns the fields this principal may read; omitted means all requested. */
|
|
116
|
+
readonly authorize?: (principal: P, fields: readonly string[]) => readonly string[];
|
|
117
|
+
/**
|
|
118
|
+
* Decides, per record, what a principal sees of the fields `authorize`
|
|
119
|
+
* allowed: run once per read, before `read`. A member it drops from a
|
|
120
|
+
* record is settled unread, as one the source did not return.
|
|
121
|
+
*/
|
|
122
|
+
readonly filter?: (principal: P, fields: readonly string[]) => Effect.Effect<ReadPlan, RemoteServerError, R>;
|
|
123
|
+
/**
|
|
124
|
+
* The rule that decides which rows this source returns, as it was given one
|
|
125
|
+
* (a Drizzle binding's `visible`, `RemoteServer.memory`'s `readable`). The
|
|
126
|
+
* server never runs it: it is here so a check at startup, such as
|
|
127
|
+
* `GuardServer.validate`, can confirm a source applies the rule its Entity
|
|
128
|
+
* requires.
|
|
129
|
+
*/
|
|
130
|
+
readonly visible?: unknown;
|
|
131
|
+
/**
|
|
132
|
+
* The fields every principal reads alike, of every row: no rule about who
|
|
133
|
+
* is asking hides the row or the field, or changes its value. A promise the
|
|
134
|
+
* server keeps by trusting it: the live hub sends a declared write's value
|
|
135
|
+
* of one to every subscriber as it is, with no read per principal.
|
|
136
|
+
*/
|
|
137
|
+
readonly shared?: ReadonlySet<string> | undefined;
|
|
138
|
+
/**
|
|
139
|
+
* The members answered for whoever reads them (a `Derived.exists`): a
|
|
140
|
+
* server mounting this source must have a `viewer`, and refuses to be made
|
|
141
|
+
* without one.
|
|
142
|
+
*/
|
|
143
|
+
readonly perViewer?: ReadonlyArray<string> | undefined;
|
|
144
|
+
}
|
|
145
|
+
/** What `EntitySource.filter` decides for one read. */
|
|
146
|
+
interface ReadPlan {
|
|
147
|
+
/** The fields to read: those allowed, and any the decision itself needs. */
|
|
148
|
+
readonly fields: readonly string[];
|
|
149
|
+
/** One record as the principal sees it: a member dropped, or its value replaced. */
|
|
150
|
+
readonly apply: (record: EntityRecord) => EntityRecord;
|
|
151
|
+
}
|
|
152
|
+
/**
|
|
153
|
+
* A read as the handlers make it for `context.principal`: the asked fields the
|
|
154
|
+
* source declares and `authorize` allows, through `filter`, each record holding
|
|
155
|
+
* no other field. None when the principal may read none of the fields asked,
|
|
156
|
+
* so a caller can tell nothing to read from a row that is gone.
|
|
157
|
+
*/
|
|
158
|
+
declare const readAs: <P, R>(source: EntitySource<P, R>, context: EntitySourceContext<P>) => Effect.Effect<Option.Option<ReadonlyArray<EntityRecord>>, RemoteServerError, R>;
|
|
159
|
+
/**
|
|
160
|
+
* Where a declared write lands: one row's new values, encoded as the store holds
|
|
161
|
+
* them. With `expect`, the row is written only while its revision is still that
|
|
162
|
+
* value, and the revision moves on with the write. With `when`, only while the
|
|
163
|
+
* row holds its body, checked in the statement that writes it; a row there at
|
|
164
|
+
* the expected revision that does not hold it fails with `RemoteUnmet`. The row
|
|
165
|
+
* as written answers; none when no row matched.
|
|
166
|
+
*/
|
|
167
|
+
/**
|
|
168
|
+
* What the row an update or a delete finds must hold for it to land, judged
|
|
169
|
+
* in the statement that writes it: a guard's rule that reads another row (a
|
|
170
|
+
* path, an exists), against what that row holds as the statement runs.
|
|
171
|
+
*/
|
|
172
|
+
type RowRequirement = Data.TaggedEnum<{
|
|
173
|
+
/** A body over the row, with its input and what its context terms read. */
|
|
174
|
+
Body: {
|
|
175
|
+
readonly query: AnyQuery;
|
|
176
|
+
readonly input: Readonly<Record<string, unknown>>;
|
|
177
|
+
readonly context: ExprContext;
|
|
178
|
+
};
|
|
179
|
+
All: {
|
|
180
|
+
readonly of: ReadonlyArray<RowRequirement>;
|
|
181
|
+
};
|
|
182
|
+
Any: {
|
|
183
|
+
readonly of: ReadonlyArray<RowRequirement>;
|
|
184
|
+
};
|
|
185
|
+
}>;
|
|
186
|
+
declare const RowRequirement: Data.TaggedEnum.Constructor<{
|
|
187
|
+
readonly _tag: "All";
|
|
188
|
+
readonly of: ReadonlyArray<RowRequirement>;
|
|
189
|
+
} | {
|
|
190
|
+
readonly _tag: "Any";
|
|
191
|
+
readonly of: ReadonlyArray<RowRequirement>;
|
|
192
|
+
} | {
|
|
193
|
+
readonly _tag: "Body";
|
|
194
|
+
readonly query: AnyQuery;
|
|
195
|
+
readonly input: Readonly<Record<string, unknown>>;
|
|
196
|
+
readonly context: ExprContext;
|
|
197
|
+
}>;
|
|
198
|
+
/** A row requirement, and the words a refusal of it gives, when its rule explains itself. */
|
|
199
|
+
interface WriteRequirement {
|
|
200
|
+
readonly holds: RowRequirement;
|
|
201
|
+
readonly reason: Option.Option<string>;
|
|
202
|
+
}
|
|
203
|
+
interface EntityWriter<P, R = never> {
|
|
204
|
+
readonly entity: string;
|
|
205
|
+
/**
|
|
206
|
+
* Whether `update` and `delete` hold the row to their `requires` in the
|
|
207
|
+
* statement that writes it, and refuse one that does not with
|
|
208
|
+
* `Forbidden`. A guard hands such a writer the rules it cannot judge over
|
|
209
|
+
* one row, and refuses to wrap a writer without it.
|
|
210
|
+
*/
|
|
211
|
+
readonly requires?: true;
|
|
212
|
+
/**
|
|
213
|
+
* Whether `update` and `delete` honour `when`. `RemoteServer.write` refuses
|
|
214
|
+
* a write with a precondition over a writer without it, which would write
|
|
215
|
+
* whatever the row held.
|
|
216
|
+
*/
|
|
217
|
+
readonly preconditions?: true;
|
|
218
|
+
/**
|
|
219
|
+
* Whether `update` adds `increments` to their fields where it writes.
|
|
220
|
+
* `RemoteServer.write` refuses a write with an increment over a writer
|
|
221
|
+
* without it, which would leave the fields where they were.
|
|
222
|
+
*/
|
|
223
|
+
readonly increments?: true;
|
|
224
|
+
/**
|
|
225
|
+
* Whether `update` computes `assignments` where it writes, over the row it
|
|
226
|
+
* writes. `RemoteServer.write` refuses a write computing a field over a
|
|
227
|
+
* writer without it.
|
|
228
|
+
*/
|
|
229
|
+
readonly assignments?: true;
|
|
230
|
+
/**
|
|
231
|
+
* The memory table this writer works out the row a write leaves by
|
|
232
|
+
* (`Write.apply`'s), where its own statement computes it: what a wrapping
|
|
233
|
+
* writer (a guard) judges by, so it judges the value the database writes.
|
|
234
|
+
*/
|
|
235
|
+
readonly operators?: MemoryOperators | undefined;
|
|
236
|
+
/**
|
|
237
|
+
* Whether `update` writes only the row it read, at the revision it read it,
|
|
238
|
+
* whatever the write `expect`s: what a guard does so its rules judge the row
|
|
239
|
+
* written. Concurrent writes then cannot interleave, so an increment of a
|
|
240
|
+
* real number, or any computed assignment, needs no `expect` of its own.
|
|
241
|
+
*/
|
|
242
|
+
readonly pins?: true;
|
|
243
|
+
/**
|
|
244
|
+
* Whether `assignment`, landed without `expect`, gives one result whatever
|
|
245
|
+
* order concurrent writes land in: its operator `op(field, amount)`, with
|
|
246
|
+
* commutativity and associativity tested for the implementations this
|
|
247
|
+
* writer runs. `RemoteServer.write` asks of each computed assignment a
|
|
248
|
+
* write lands without a revision.
|
|
249
|
+
*/
|
|
250
|
+
readonly commutes?: (assignment: WriteAssignment) => boolean;
|
|
251
|
+
/**
|
|
252
|
+
* Whether `update` and `insert` record each write they land under its
|
|
253
|
+
* `operation`, in the transaction that writes, and answer a retry of it from
|
|
254
|
+
* that record rather than writing again. An increment that expects no
|
|
255
|
+
* revision needs one, and so does a create a client may send again.
|
|
256
|
+
*/
|
|
257
|
+
readonly ledger?: true;
|
|
258
|
+
/**
|
|
259
|
+
* Whether `update` and `insert` refuse a row, or a change, that would break
|
|
260
|
+
* one of its Entity's invariants (`Entity.invariant`), with `RemoteInvalid`,
|
|
261
|
+
* judged over the rows they write; an insert judges the state invariants
|
|
262
|
+
* alone. `RemoteServer.write` refuses a write the Entity holds to any through
|
|
263
|
+
* a writer without it.
|
|
264
|
+
*/
|
|
265
|
+
readonly invariants?: true;
|
|
266
|
+
/**
|
|
267
|
+
* Why this writer cannot land `write`, each a sentence; none when it can.
|
|
268
|
+
* `RemoteServer.write` asks once, where the write is registered, for what
|
|
269
|
+
* only the store knows: a column's type, say, which the Entity does not say.
|
|
270
|
+
*/
|
|
271
|
+
readonly refuses?: (write: AnyWrite) => ReadonlyArray<string>;
|
|
272
|
+
/**
|
|
273
|
+
* The answer recorded for `operation`, when this writer has a ledger and
|
|
274
|
+
* holds one: what a wrapping writer (a guard) answers a retry with, without
|
|
275
|
+
* deciding again over a row that has moved since. One recorded for another
|
|
276
|
+
* `request` fails.
|
|
277
|
+
*/
|
|
278
|
+
readonly recorded?: (context: {
|
|
279
|
+
readonly operation: string;
|
|
280
|
+
/**
|
|
281
|
+
* What was asked: the mutation's name, the keys it writes and its input,
|
|
282
|
+
* encoded, as one text. Every retry of `operation` asks the same, so a
|
|
283
|
+
* ledger holding the operation for another request refuses this one.
|
|
284
|
+
*/
|
|
285
|
+
readonly request: string;
|
|
286
|
+
/** The row the operation writes: one operation may write several rows. */
|
|
287
|
+
readonly id: string;
|
|
288
|
+
readonly principal: P;
|
|
289
|
+
}) => Effect.Effect<Option.Option<Readonly<Record<string, unknown>>>, RemoteServerError, R>;
|
|
290
|
+
readonly update: (context: {
|
|
291
|
+
readonly id: string;
|
|
292
|
+
/** The operation's identity across clients, when the client sent one: a ledger's key. */
|
|
293
|
+
readonly operation: Option.Option<string>;
|
|
294
|
+
/**
|
|
295
|
+
* What was asked: the mutation's name, the keys it writes and its input,
|
|
296
|
+
* encoded, as one text. Every retry of `operation` asks the same, so a
|
|
297
|
+
* ledger holding the operation for another request refuses this one.
|
|
298
|
+
*/
|
|
299
|
+
readonly request: string;
|
|
300
|
+
readonly values: Readonly<Record<string, unknown>>;
|
|
301
|
+
/**
|
|
302
|
+
* Each field to move, by the amount, encoded: added to the stored value in
|
|
303
|
+
* the statement that writes, never computed from a value read before it.
|
|
304
|
+
*/
|
|
305
|
+
readonly increments: Readonly<Record<string, number>>;
|
|
306
|
+
/**
|
|
307
|
+
* Each field to compute, as data (`Write.bind`'s): run in the statement
|
|
308
|
+
* that writes, over the row as it is there.
|
|
309
|
+
*/
|
|
310
|
+
readonly assignments: Readonly<Record<string, Computation>>;
|
|
311
|
+
/** Each `one` relation it points, by the relation's key: the row, or none. */
|
|
312
|
+
readonly links: Readonly<Record<string, Option.Option<EntityRef>>>;
|
|
313
|
+
readonly expect: Option.Option<{
|
|
314
|
+
readonly field: string;
|
|
315
|
+
readonly revision: unknown;
|
|
316
|
+
}>;
|
|
317
|
+
readonly when: Option.Option<WriteWhen>;
|
|
318
|
+
/** What the row must hold, judged where it is written; only a writer with `requires` is given one. */
|
|
319
|
+
readonly requires?: WriteRequirement | undefined;
|
|
320
|
+
readonly principal: P;
|
|
321
|
+
}) => Effect.Effect<Option.Option<Readonly<Record<string, unknown>>>, RemoteServerError | RemoteForbidden | RemoteUnmet | RemoteInvalid, R>;
|
|
322
|
+
/**
|
|
323
|
+
* Inserts the row and answers it. An id already taken fails with
|
|
324
|
+
* `RemoteTaken`, whatever the row there holds and whether its asker may see
|
|
325
|
+
* it, so a create never tells what it may not read; unless the writer's
|
|
326
|
+
* ledger records `operation` as the insert that made it (a retry), answered
|
|
327
|
+
* with the row as it now is.
|
|
328
|
+
*/
|
|
329
|
+
readonly insert: (context: {
|
|
330
|
+
readonly id: string;
|
|
331
|
+
/** The operation's identity across clients, when the client sent one: a ledger's key. */
|
|
332
|
+
readonly operation: Option.Option<string>;
|
|
333
|
+
/**
|
|
334
|
+
* What was asked: the mutation's name, the keys it writes and its input,
|
|
335
|
+
* encoded, as one text. Every retry of `operation` asks the same, so a
|
|
336
|
+
* ledger holding the operation for another request refuses this one.
|
|
337
|
+
*/
|
|
338
|
+
readonly request: string;
|
|
339
|
+
readonly values: Readonly<Record<string, unknown>>;
|
|
340
|
+
readonly links: Readonly<Record<string, Option.Option<EntityRef>>>;
|
|
341
|
+
readonly principal: P;
|
|
342
|
+
}) => Effect.Effect<Readonly<Record<string, unknown>>, RemoteServerError | RemoteForbidden | RemoteInvalid | RemoteTaken, R>;
|
|
343
|
+
/**
|
|
344
|
+
* Deletes the row, while it is still at the revision when one is expected:
|
|
345
|
+
* `deleted`, `absent` (no row, so nothing to delete; a retry's case), or
|
|
346
|
+
* `moved` (the row is there at another revision, and stays).
|
|
347
|
+
*/
|
|
348
|
+
readonly delete: (context: {
|
|
349
|
+
readonly id: string;
|
|
350
|
+
readonly expect: Option.Option<{
|
|
351
|
+
readonly field: string;
|
|
352
|
+
readonly revision: unknown;
|
|
353
|
+
}>;
|
|
354
|
+
readonly when: Option.Option<WriteWhen>;
|
|
355
|
+
/** What the row must hold, judged where it is deleted; only a writer with `requires` is given one. */
|
|
356
|
+
readonly requires?: WriteRequirement | undefined;
|
|
357
|
+
readonly principal: P;
|
|
358
|
+
}) => Effect.Effect<'deleted' | 'absent' | 'moved', RemoteServerError | RemoteForbidden | RemoteUnmet, R>;
|
|
359
|
+
/**
|
|
360
|
+
* The row as `principal` may see it, under the read rule its Source applies:
|
|
361
|
+
* none when there is no such row, or it is hidden. Given, a write's answer
|
|
362
|
+
* is read back through it, so an answer never shows its writer a row it may
|
|
363
|
+
* not read, and a row the write hid from them answers as deleted.
|
|
364
|
+
*/
|
|
365
|
+
readonly read?: (context: {
|
|
366
|
+
readonly id: string;
|
|
367
|
+
readonly fields: ReadonlyArray<string>;
|
|
368
|
+
readonly principal: P;
|
|
369
|
+
}) => Effect.Effect<Option.Option<Readonly<Record<string, unknown>>>, RemoteServerError, R>;
|
|
370
|
+
/**
|
|
371
|
+
* Each of `relations`' links as stored, by ref key (`'Project:p1'`) or
|
|
372
|
+
* `null`, whatever a reader may see of the row it points at; none when there
|
|
373
|
+
* is no such row. A guard reads it to tell a write that unlinks a row hidden
|
|
374
|
+
* from its writer from one that changes nothing.
|
|
375
|
+
*/
|
|
376
|
+
readonly linked?: (context: {
|
|
377
|
+
readonly id: string;
|
|
378
|
+
readonly relations: ReadonlyArray<string>;
|
|
379
|
+
}) => Effect.Effect<Option.Option<Readonly<Record<string, unknown>>>, RemoteServerError, R>;
|
|
380
|
+
}
|
|
381
|
+
/** A connection change a mutation made, as the wire carries it. */
|
|
382
|
+
type ConnectionChange = Schema.Schema.Type<typeof ConnectionChangeSchema>;
|
|
383
|
+
/**
|
|
384
|
+
* The requested fields, in request order, that the source declares and the
|
|
385
|
+
* principal may read. Never a field the client did not request, even if a
|
|
386
|
+
* permissive `authorize` returns more.
|
|
387
|
+
*/
|
|
388
|
+
declare const allowedFields: <P, R>(source: EntitySource<P, R>, principal: P, requested: ReadonlyArray<string>) => ReadonlyArray<string>;
|
|
389
|
+
interface MutationOutcome<Output> {
|
|
390
|
+
readonly output: Output;
|
|
391
|
+
readonly entities?: ReadonlyArray<NormalizedPatch>;
|
|
392
|
+
/** Connection changes the mutation made; the client settles them with its patches. */
|
|
393
|
+
readonly connections?: ReadonlyArray<ConnectionChange>;
|
|
394
|
+
/**
|
|
395
|
+
* Entities the mutation deleted. The client knows them absent from then on:
|
|
396
|
+
* they leave every connection and read `NotFound`, with no connection to name.
|
|
397
|
+
*/
|
|
398
|
+
readonly deleted?: ReadonlyArray<{
|
|
399
|
+
readonly entity: string;
|
|
400
|
+
readonly id: string;
|
|
401
|
+
}>;
|
|
402
|
+
}
|
|
403
|
+
interface MutationSource<P, R = never> {
|
|
404
|
+
readonly mutation: string;
|
|
405
|
+
/**
|
|
406
|
+
* For a declared write (`RemoteServer.write`), the Entity it writes, the
|
|
407
|
+
* writer it lands through, as it was given one, and the write itself. The
|
|
408
|
+
* server never reads it; a startup check such as `GuardServer.validate` does.
|
|
409
|
+
*/
|
|
410
|
+
readonly writes?: {
|
|
411
|
+
readonly entity: string;
|
|
412
|
+
readonly writer: unknown;
|
|
413
|
+
readonly write: AnyWrite;
|
|
414
|
+
};
|
|
415
|
+
readonly Input: Schema.Codec<unknown>;
|
|
416
|
+
readonly Output: Schema.Codec<unknown>;
|
|
417
|
+
readonly Refusal: Schema.Codec<unknown, unknown>;
|
|
418
|
+
readonly run: (context: {
|
|
419
|
+
readonly input: unknown;
|
|
420
|
+
readonly principal: P;
|
|
421
|
+
/**
|
|
422
|
+
* Who asks, as a row (`RemoteServer.make`'s `viewer`), or none for a
|
|
423
|
+
* visitor: what a declared write's `Expr.viewer` sets (`Entity.sets`).
|
|
424
|
+
*/
|
|
425
|
+
readonly viewer: Option.Option<EntityRef>;
|
|
426
|
+
/**
|
|
427
|
+
* The client's id for this request, the same on every retry of it. It is
|
|
428
|
+
* unique within that client only: two clients' first requests can share
|
|
429
|
+
* it. Key a record of the write by `operation`, never by this.
|
|
430
|
+
*/
|
|
431
|
+
readonly requestId: string;
|
|
432
|
+
/**
|
|
433
|
+
* The operation's identity across clients, the same on every retry of it,
|
|
434
|
+
* when the client sent one (Remote's does); none from an older client.
|
|
435
|
+
*/
|
|
436
|
+
readonly operation: Option.Option<string>;
|
|
437
|
+
/**
|
|
438
|
+
* The write's time, in milliseconds since the epoch: when the reader
|
|
439
|
+
* acted, as the client sent it, if within the server's `clockSkew` of its
|
|
440
|
+
* own clock; otherwise the server's own. What a declared insert's
|
|
441
|
+
* `Expr.now` sets (`Entity.sets`).
|
|
442
|
+
*/
|
|
443
|
+
readonly now: number;
|
|
444
|
+
/**
|
|
445
|
+
* One row of another Entity as the asker may see it, through the server's
|
|
446
|
+
* own source for it (its read rule, the viewer): none for a row hidden or
|
|
447
|
+
* not there. What a declared write reads a path from the viewer with.
|
|
448
|
+
*/
|
|
449
|
+
readonly read: (ref: EntityRef, fields: ReadonlyArray<string>) => Effect.Effect<Option.Option<Readonly<Record<string, unknown>>>, RemoteServerError>;
|
|
450
|
+
/** For a declared write: the input keys to write, when the client named only some. */
|
|
451
|
+
readonly keys?: ReadonlyArray<string> | undefined;
|
|
452
|
+
}) => Effect.Effect<{
|
|
453
|
+
readonly output: unknown;
|
|
454
|
+
readonly entities: ReadonlyArray<NormalizedPatch>;
|
|
455
|
+
readonly connections: ReadonlyArray<ConnectionChange>;
|
|
456
|
+
readonly deleted: ReadonlyArray<{
|
|
457
|
+
readonly entity: string;
|
|
458
|
+
readonly id: string;
|
|
459
|
+
}>;
|
|
460
|
+
/**
|
|
461
|
+
* Rows the written row points at, before and after the write, whose
|
|
462
|
+
* derived members it may have changed: the answer reads what the client
|
|
463
|
+
* shows of each, and sends no patch of its own for them.
|
|
464
|
+
*/
|
|
465
|
+
readonly pointed?: ReadonlyArray<{
|
|
466
|
+
readonly entity: string;
|
|
467
|
+
readonly id: string;
|
|
468
|
+
}>;
|
|
469
|
+
}, RemoteServerError | MutationRefused | RemoteForbidden, R>;
|
|
470
|
+
}
|
|
471
|
+
interface QueryPage {
|
|
472
|
+
readonly edges: ReadonlyArray<{
|
|
473
|
+
readonly entity: string;
|
|
474
|
+
readonly id: string;
|
|
475
|
+
readonly key: string;
|
|
476
|
+
}>;
|
|
477
|
+
readonly start: Boundary;
|
|
478
|
+
readonly end: Boundary;
|
|
479
|
+
}
|
|
480
|
+
interface QuerySource<P, R = never> {
|
|
481
|
+
readonly query: string;
|
|
482
|
+
/** The entity whose rows it lists: a list read live selects rows of no other. */
|
|
483
|
+
readonly entity: string;
|
|
484
|
+
readonly Input: Schema.Codec<unknown>;
|
|
485
|
+
readonly run: (context: {
|
|
486
|
+
readonly input: unknown;
|
|
487
|
+
readonly window: QueryWindow;
|
|
488
|
+
readonly principal: P;
|
|
489
|
+
/** As `EntitySourceContext.viewer`: what a body's `Expr.viewer` reads. */
|
|
490
|
+
readonly viewer?: Option.Option<EntityRef> | undefined;
|
|
491
|
+
/**
|
|
492
|
+
* What the client reads of each item. A source may use it to answer
|
|
493
|
+
* fields with the page, or ignore it: the handlers fetch what the page
|
|
494
|
+
* leaves out through the entity sources, so one response still carries
|
|
495
|
+
* both either way.
|
|
496
|
+
*/
|
|
497
|
+
readonly select?: RelationRequirement | undefined;
|
|
498
|
+
}) => Effect.Effect<QueryPage, RemoteServerError, R>;
|
|
499
|
+
/** The rule that decides which rows the query lists. See `EntitySource.visible`. */
|
|
500
|
+
readonly visible?: unknown;
|
|
501
|
+
}
|
|
502
|
+
/**
|
|
503
|
+
* A list a subscriber reads live (`Data.query(…, { live: true })`), admitted
|
|
504
|
+
* and resolved by `handlers`: what a live source diffs to tell a row that
|
|
505
|
+
* joins, changes or leaves it.
|
|
506
|
+
*/
|
|
507
|
+
interface LiveQuery<R = never> {
|
|
508
|
+
/** The connection, as the client keys it: the query's name and input. */
|
|
509
|
+
readonly identity: string;
|
|
510
|
+
/** What its read selects of each row, of the entity it lists. */
|
|
511
|
+
readonly select: RelationRequirement;
|
|
512
|
+
/** Its window as the subscriber reads it now: the registered query, run as them. */
|
|
513
|
+
readonly edges: Effect.Effect<QueryPage['edges'], RemoteServerError, R>;
|
|
514
|
+
}
|
|
515
|
+
interface LiveSource<P, R = never> {
|
|
516
|
+
readonly entity: string;
|
|
517
|
+
/**
|
|
518
|
+
* Called by `handlers` only with requirements it has admitted: no more
|
|
519
|
+
* distinct ids of one entity than `maxIdsPerEntity` (a live list's `first`
|
|
520
|
+
* counted with them), and no more pages of one relation than a read may
|
|
521
|
+
* ask. A larger subscription is refused with `RemoteLiveRefused` before any
|
|
522
|
+
* live source is asked.
|
|
523
|
+
*
|
|
524
|
+
* A method, not a function property: `queries` carries `R` into the
|
|
525
|
+
* parameter, which would make a source of `R = never` no `LiveSource<any, any>`.
|
|
526
|
+
*/
|
|
527
|
+
subscribe(context: {
|
|
528
|
+
readonly requirements: ReadonlyArray<Requirement>;
|
|
529
|
+
/** The lists of this entity the subscriber reads live. */
|
|
530
|
+
readonly queries: ReadonlyArray<LiveQuery<R>>;
|
|
531
|
+
readonly after: number;
|
|
532
|
+
readonly principal: P;
|
|
533
|
+
/** As `EntitySourceContext.viewer`, for the re-reads it makes. */
|
|
534
|
+
readonly viewer?: Option.Option<EntityRef> | undefined;
|
|
535
|
+
}): Stream.Stream<Schema.Schema.Type<typeof LiveChange>, RemoteServerError, R>;
|
|
536
|
+
/**
|
|
537
|
+
* The entity source every value it sends is read through, as
|
|
538
|
+
* `RemoteServer.readAs` reads (`pollLive` sets it). The server never reads
|
|
539
|
+
* it: a startup check such as `GuardServer.validate` does, to accept a live
|
|
540
|
+
* source over the source it has checked.
|
|
541
|
+
*/
|
|
542
|
+
readonly reads?: EntitySource<P, R> | undefined;
|
|
543
|
+
}
|
|
544
|
+
interface ServerDefinition<P, R = never> {
|
|
545
|
+
readonly entities: ReadonlyMap<string, EntitySource<P, R>>;
|
|
546
|
+
readonly mutations: ReadonlyMap<string, MutationSource<P, R>>;
|
|
547
|
+
readonly queries: ReadonlyMap<string, QuerySource<P, R>>;
|
|
548
|
+
readonly live: ReadonlyMap<string, LiveSource<P, R>>;
|
|
549
|
+
/** Who asks, as a row: what a declared write's `Expr.viewer` sets. See `make`. */
|
|
550
|
+
readonly viewer?: ((principal: P) => Option.Option<EntityRef>) | undefined;
|
|
551
|
+
/** How far from its own clock a client's time may be and still be the write's. See `make`. */
|
|
552
|
+
readonly clockSkew?: Duration.Duration | undefined;
|
|
553
|
+
}
|
|
554
|
+
/**
|
|
555
|
+
* What a body's `Expr.viewer` and `Expr.now` read on this server: the viewer
|
|
556
|
+
* the request was given, and the server's clock. A body that reads the viewer
|
|
557
|
+
* in a run given none (not through a server) is refused, never read as a
|
|
558
|
+
* visitor's.
|
|
559
|
+
*/
|
|
560
|
+
declare const exprContext: (body: AnyQuery, viewer: Option.Option<EntityRef> | undefined, now: number) => ExprContext;
|
|
561
|
+
interface HandlerOptions<P, R = never> {
|
|
562
|
+
/**
|
|
563
|
+
* A read or live subscription may not name more ids of one entity than
|
|
564
|
+
* this; default 1000. A live subscription over it is refused with
|
|
565
|
+
* `RemoteLiveRefused` before any live source or the hub sees it.
|
|
566
|
+
*/
|
|
567
|
+
readonly maxIdsPerEntity?: number | undefined;
|
|
568
|
+
/** A nested selection may not reach further than this many relation levels; default 8. */
|
|
569
|
+
readonly maxDepth?: number | undefined;
|
|
570
|
+
/** A hub whose `changed`/`deleted` signals reach the subscribers this handler registers. */
|
|
571
|
+
readonly live?: LiveHub<P, R> | undefined;
|
|
572
|
+
}
|
|
573
|
+
type LiveChangeValue = Schema.Schema.Type<typeof LiveChange>;
|
|
574
|
+
interface LiveRef {
|
|
575
|
+
readonly entity: string;
|
|
576
|
+
readonly id: string;
|
|
577
|
+
}
|
|
578
|
+
/**
|
|
579
|
+
* The server-side "these fields changed" signal. A hub tracks each live
|
|
580
|
+
* subscriber's requirements (entity, id, fields) and principal; `changed`
|
|
581
|
+
* re-reads the changed fields a subscriber selects through the entity's own
|
|
582
|
+
* source, under that subscriber's principal, and streams the patch to it.
|
|
583
|
+
* Subscribers that select none of the changed fields do no work. Cursors
|
|
584
|
+
* continue from the cursor each subscriber resumed at, so the client's
|
|
585
|
+
* duplicate and gap handling is unchanged.
|
|
586
|
+
*/
|
|
587
|
+
interface LiveHub<P, R = never> {
|
|
588
|
+
/**
|
|
589
|
+
* `values`, when given, are the row's stored values of `fields` (a declared
|
|
590
|
+
* write's answer): a field of them the source declares `shared` is sent as
|
|
591
|
+
* it is, and only the rest are re-read.
|
|
592
|
+
*/
|
|
593
|
+
readonly changed: (ref: LiveRef, fields: ReadonlyArray<string>, values?: Readonly<Record<string, unknown>> | undefined) => Effect.Effect<void, RemoteServerError, R>;
|
|
594
|
+
/**
|
|
595
|
+
* `ref` may be gone: each subscriber's selection of it is read again, and
|
|
596
|
+
* one it is no longer there to is sent a deletion. A row deleted for one
|
|
597
|
+
* writer may only be hidden from them, and still there to others.
|
|
598
|
+
*/
|
|
599
|
+
readonly deleted: (ref: LiveRef) => Effect.Effect<void, RemoteServerError, R>;
|
|
600
|
+
/**
|
|
601
|
+
* Registers a subscriber for the stream's lifetime; `handlers` calls this,
|
|
602
|
+
* with requirements it has admitted (see `LiveSource.subscribe`).
|
|
603
|
+
*/
|
|
604
|
+
readonly subscribe: (context: {
|
|
605
|
+
readonly requirements: ReadonlyArray<Requirement>;
|
|
606
|
+
readonly after: number;
|
|
607
|
+
readonly principal: P;
|
|
608
|
+
/** As `EntitySourceContext.viewer`, for the re-reads it makes. */
|
|
609
|
+
readonly viewer?: Option.Option<EntityRef> | undefined;
|
|
610
|
+
}) => Stream.Stream<LiveChangeValue, RemoteServerError>;
|
|
611
|
+
/** How many subscribers are registered now. */
|
|
612
|
+
readonly size: Effect.Effect<number>;
|
|
613
|
+
}
|
|
614
|
+
declare const liveHub: <P, R>(entities: ReadonlyArray<EntitySource<P, R>>, options?: {
|
|
615
|
+
/**
|
|
616
|
+
* Who a principal is, for sharing re-reads: subscribers whose principals
|
|
617
|
+
* have one key share one read, under the first one's principal. Default:
|
|
618
|
+
* the principal itself, so only the same value shares. A source with
|
|
619
|
+
* members answered per viewer (`perViewer`, a `Derived.exists`) is read
|
|
620
|
+
* once per viewer within a key, so a key coarser than who asks (a role)
|
|
621
|
+
* never sends one reader's value of such a member to another.
|
|
622
|
+
*/
|
|
623
|
+
readonly key?: ((principal: P) => unknown) | undefined;
|
|
624
|
+
}) => Effect.Effect<LiveHub<P, R>>;
|
|
625
|
+
/**
|
|
626
|
+
* A descriptor's name and, when it declares them, its readable members: an
|
|
627
|
+
* Entity's `members` (its fields, relations and derived members), or a plain
|
|
628
|
+
* descriptor's `fields`.
|
|
629
|
+
*/
|
|
630
|
+
interface EntityName {
|
|
631
|
+
readonly name: string;
|
|
632
|
+
readonly fields?: Readonly<Record<string, unknown>> | undefined;
|
|
633
|
+
readonly members?: Readonly<Record<string, unknown>> | undefined;
|
|
634
|
+
}
|
|
635
|
+
/** One entity's rows in their wire shape: a relation is its ref key, `'User:u1'`. */
|
|
636
|
+
type MemoryRows = Readonly<Record<string, ReadonlyArray<Readonly<Record<string, unknown>> & {
|
|
637
|
+
readonly id: string;
|
|
638
|
+
}>>>;
|
|
639
|
+
/**
|
|
640
|
+
* The rows a memory backend holds, which its mutations write through. A
|
|
641
|
+
* change is what the next read sees; nothing is pushed to a client.
|
|
642
|
+
*/
|
|
643
|
+
interface MemoryStore {
|
|
644
|
+
/** The rows of one entity, in insertion order. */
|
|
645
|
+
readonly rows: (entity: string) => ReadonlyArray<Readonly<Record<string, unknown>>>;
|
|
646
|
+
/** Writes these values onto a row, creating it if it is new. */
|
|
647
|
+
readonly write: (entity: string, id: string, values: Readonly<Record<string, unknown>>) => void;
|
|
648
|
+
readonly remove: (entity: string, id: string) => void;
|
|
649
|
+
}
|
|
650
|
+
/**
|
|
651
|
+
* A memory backend made without a `principal`: its rows and the server over
|
|
652
|
+
* them, answered as whoever its caller names per request (`serveFetch`,
|
|
653
|
+
* `RemoteServer.handlers(served.server, principal)`).
|
|
654
|
+
*/
|
|
655
|
+
interface MemoryServed<P> extends MemoryStore {
|
|
656
|
+
/**
|
|
657
|
+
* The rows' server, for serving them over a real transport, or as any
|
|
658
|
+
* principal: `RemoteRpc.toLayer(RemoteServer.handlers(backend.server, principal))`.
|
|
659
|
+
*/
|
|
660
|
+
readonly server: ServerDefinition<P>;
|
|
661
|
+
}
|
|
662
|
+
interface MemoryBackend<P = undefined> extends MemoryServed<P> {
|
|
663
|
+
/**
|
|
664
|
+
* A `RemoteClient` answering from the rows as the configured `principal`.
|
|
665
|
+
* Provide it where the real one would go.
|
|
666
|
+
*/
|
|
667
|
+
readonly layer: Layer.Layer<RemoteClient>;
|
|
668
|
+
}
|
|
669
|
+
/** What `RemoteServer.memory` is made from. See `memory`. */
|
|
670
|
+
type MemoryConfig<P> = {
|
|
671
|
+
readonly domain: Pick<RemoteDescriptor, 'registry'>;
|
|
672
|
+
readonly rows: MemoryRows;
|
|
673
|
+
/**
|
|
674
|
+
* How the bodies' primitive operators are run: every query body is checked
|
|
675
|
+
* against it where the server is built, and one calling an operator it lacks
|
|
676
|
+
* is refused there. `Operators.kernel` when not given.
|
|
677
|
+
*/
|
|
678
|
+
readonly operators?: MemoryOperators | undefined;
|
|
679
|
+
/**
|
|
680
|
+
* Sources for entities the domain does not declare, which no row backs (a
|
|
681
|
+
* `Me` row answered from the principal, `GuardServer.me`), served beside
|
|
682
|
+
* the rows. One for a declared entity is refused: the rows serve it.
|
|
683
|
+
*/
|
|
684
|
+
readonly entities?: ReadonlyArray<EntitySource<P>>;
|
|
685
|
+
/** Sources for queries, beside the domain's: one named as a declared query answers it instead of its body. */
|
|
686
|
+
readonly queries?: ReadonlyArray<QuerySource<P>>;
|
|
687
|
+
readonly mutations?: (store: MemoryStore) => ReadonlyArray<MutationSource<P>>;
|
|
688
|
+
/** Per entity name, the fields a principal may read, as `RemoteServer.entity` takes it. */
|
|
689
|
+
readonly authorize?: Readonly<Record<string, NonNullable<EntitySource<P>['authorize']>>>;
|
|
690
|
+
/** Per entity name, what a principal sees of each record, as `RemoteServer.entity` takes it. */
|
|
691
|
+
readonly filter?: Readonly<Record<string, NonNullable<EntitySource<P>['filter']>>>;
|
|
692
|
+
/** Per entity name, the fields every principal reads alike: see `EntitySource.shared`. */
|
|
693
|
+
readonly shared?: Readonly<Record<string, ReadonlyArray<string>>>;
|
|
694
|
+
/**
|
|
695
|
+
* Which stored rows a principal may read, decided once per read. A row it
|
|
696
|
+
* may not read is absent from a read by id and from every query, and a ref
|
|
697
|
+
* to one is dropped from a relation (a `one` ref reads as `null`). `row`
|
|
698
|
+
* looks another stored row up, for a decision that follows a relation.
|
|
699
|
+
*/
|
|
700
|
+
readonly readable?: (principal: P, row: (entity: string, id: string) => Option.Option<Readonly<Record<string, unknown>>>) => Effect.Effect<MemoryReadable, RemoteServerError>;
|
|
701
|
+
/** Who the `layer` answers as. Without it there is no `layer`, unless `P` admits `undefined`. */
|
|
702
|
+
readonly principal?: P;
|
|
703
|
+
/** Who asks, as a row: what a declared write's `Expr.viewer` sets. See `make`. */
|
|
704
|
+
readonly viewer?: ((principal: P) => Option.Option<EntityRef>) | undefined;
|
|
705
|
+
};
|
|
706
|
+
/** What a backend needs to give a `layer`: a principal to answer as, or one `undefined` can be. */
|
|
707
|
+
type MemoryAnswering<P> = undefined extends P ? unknown : {
|
|
708
|
+
readonly principal: P;
|
|
709
|
+
};
|
|
710
|
+
/** Whether a stored row of `entity` may be read, given its whole stored values. */
|
|
711
|
+
type MemoryReadable = (entity: string, row: Readonly<Record<string, unknown>>) => boolean;
|
|
712
|
+
/**
|
|
713
|
+
* A backend held in memory: the rows you give it, served through the same
|
|
714
|
+
* handlers a real server uses. For a first run, a test, a story or a demo, with
|
|
715
|
+
* no database and no network.
|
|
716
|
+
*
|
|
717
|
+
* Reads go through `handlers`, so field filtering and nested relations behave
|
|
718
|
+
* as they do in production. A query declared with `Query.define` is answered
|
|
719
|
+
* by running its body over the rows with the reference interpreter, the one
|
|
720
|
+
* every interpreter is held to by the conformance suite. A query with no body
|
|
721
|
+
* has nothing to run and is refused when the backend is made, unless `queries`
|
|
722
|
+
* supplies a source for it. Mutations are yours to give: each one writes
|
|
723
|
+
* through the store it is handed, and the next read sees the change.
|
|
724
|
+
*
|
|
725
|
+
* Every field of every row is readable unless `authorize` names the entity:
|
|
726
|
+
* then its function decides, per principal, as `RemoteServer.entity`'s does.
|
|
727
|
+
* `entities` adds Sources for entities no row backs, which the domain must not
|
|
728
|
+
* declare. The `layer` answers as `principal`, and is absent without one
|
|
729
|
+
* (unless `P` admits `undefined`); `server` answers as any. It does not push
|
|
730
|
+
* live changes. It is not a server to deploy.
|
|
731
|
+
*/
|
|
732
|
+
declare function memory<P = undefined>(config: MemoryConfig<P> & MemoryAnswering<P>): MemoryBackend<P>;
|
|
733
|
+
declare function memory<P = undefined>(config: MemoryConfig<P>): MemoryServed<P>;
|
|
734
|
+
declare const RemoteServer: {
|
|
735
|
+
/** A backend held in memory, for a first run, a test or a demo. See `memory`. */
|
|
736
|
+
memory: typeof memory;
|
|
737
|
+
/** A mutation outcome's report that `ref` now heads the connection. */
|
|
738
|
+
prepend: (connection: ConnectionIdentity, ref: {
|
|
739
|
+
readonly entity: string;
|
|
740
|
+
readonly id: string;
|
|
741
|
+
}) => ConnectionChange;
|
|
742
|
+
/** A mutation outcome's report that `ref` now ends the connection. */
|
|
743
|
+
append: (connection: ConnectionIdentity, ref: {
|
|
744
|
+
readonly entity: string;
|
|
745
|
+
readonly id: string;
|
|
746
|
+
}) => ConnectionChange;
|
|
747
|
+
/** A mutation outcome's report that `ref` left the connection. */
|
|
748
|
+
remove: (connection: ConnectionIdentity, ref: {
|
|
749
|
+
readonly entity: string;
|
|
750
|
+
readonly id: string;
|
|
751
|
+
}) => ConnectionChange;
|
|
752
|
+
/**
|
|
753
|
+
* An entity source. Given the Entity, every member it declares (fields,
|
|
754
|
+
* relations, derived members) may be requested; given anything with a
|
|
755
|
+
* `name` and `fields`, those fields. A request for anything else never
|
|
756
|
+
* reaches `read` or `authorize`. Given only a `name`, every field passes.
|
|
757
|
+
*/
|
|
758
|
+
entity: <P = unknown, R = never>(entity: EntityName, options: {
|
|
759
|
+
readonly read: EntitySource<P, R>['read'];
|
|
760
|
+
readonly authorize?: EntitySource<P, R>['authorize'];
|
|
761
|
+
readonly filter?: EntitySource<P, R>['filter'];
|
|
762
|
+
/** See `EntitySource.shared`: each must be a member the source serves. */
|
|
763
|
+
readonly shared?: ReadonlyArray<string> | undefined;
|
|
764
|
+
}) => EntitySource<P, R>;
|
|
765
|
+
mutation: <P = unknown, R = never, Name extends string = string, Input = unknown, Output = unknown, Refused = unknown>(mutation: MutationDescriptor<Name, Input, Output, Refused>, run: (context: {
|
|
766
|
+
readonly input: Input;
|
|
767
|
+
readonly principal: P;
|
|
768
|
+
/** The client's id for this request, unique within that client only. */
|
|
769
|
+
readonly requestId: string;
|
|
770
|
+
/** The operation's identity across clients, for a record of the write; see `MutationSource`. */
|
|
771
|
+
readonly operation: Option.Option<string>;
|
|
772
|
+
/** The write's time: the client's within the server's `clockSkew`, or its own; see `MutationSource`. */
|
|
773
|
+
readonly now: number;
|
|
774
|
+
}) => Effect.Effect<MutationOutcome<Output>, RemoteServerError | MutationRefused | RemoteForbidden, R>) => MutationSource<P, R>;
|
|
775
|
+
/**
|
|
776
|
+
* A refusal of `mutation`, as a value of its declared `Refusal`: fail a
|
|
777
|
+
* Source with it (`yield* RemoteServer.refuse(SavePost, { _tag: 'Field', ... })`)
|
|
778
|
+
* and the client reads it, decoded, with `Data.refusal`. `message` is what a
|
|
779
|
+
* person reads, beside it.
|
|
780
|
+
*/
|
|
781
|
+
refuse: <Refused>(mutation: MutationDescriptor<string, any, any, Refused>, refusal: NoInfer<Refused>, message?: string) => MutationRefused;
|
|
782
|
+
/**
|
|
783
|
+
* A writer's refusal of a row that does not hold the write's `when`: fail
|
|
784
|
+
* `update` or `delete` with it (`yield* RemoteServer.unmet()`), and
|
|
785
|
+
* `RemoteServer.write` answers the mutation's `Unmet` refusal.
|
|
786
|
+
*/
|
|
787
|
+
unmet: (message?: string) => RemoteUnmet;
|
|
788
|
+
/**
|
|
789
|
+
* A writer's refusal of an insert whose id a row already holds: fail
|
|
790
|
+
* `insert` with it (`yield* RemoteServer.taken()`), and `RemoteServer.write`
|
|
791
|
+
* answers the mutation's `Taken` refusal, naming the Entity and the id.
|
|
792
|
+
*/
|
|
793
|
+
taken: (message?: string) => RemoteTaken;
|
|
794
|
+
/**
|
|
795
|
+
* A writer's refusal of a row that would break an invariant: fail `update`
|
|
796
|
+
* or `insert` with it, naming the invariant's id and path when the caller
|
|
797
|
+
* may be told them, and `RemoteServer.write` answers the mutation's
|
|
798
|
+
* `Invalid` refusal.
|
|
799
|
+
*/
|
|
800
|
+
invalid: (message: string, rule?: Option.Option<string>, path?: ReadonlyArray<string>) => RemoteInvalid;
|
|
801
|
+
/**
|
|
802
|
+
* A refusal of who is asking: fail a Source with it
|
|
803
|
+
* (`yield* RemoteServer.forbid()`) and the write never runs. `reason`, when
|
|
804
|
+
* given, is what the person who asked reads; without it the refusal says
|
|
805
|
+
* nothing of why. `answer` sends it as a 403, and the client's mutation
|
|
806
|
+
* fails with `_tag: 'Forbidden'`.
|
|
807
|
+
*/
|
|
808
|
+
forbid: (reason?: string) => RemoteForbidden;
|
|
809
|
+
/**
|
|
810
|
+
* A refusal of a caller who could not be told: a `serveFetch` or
|
|
811
|
+
* `defineDocumentHost` resolver fails with it (`RemoteServer.unauthenticated()`)
|
|
812
|
+
* when the credential it was sent no longer holds. It answers 401, with
|
|
813
|
+
* `reason`, when given, for the person who asked.
|
|
814
|
+
*/
|
|
815
|
+
unauthenticated: (reason?: string) => RemoteUnauthenticated;
|
|
816
|
+
/**
|
|
817
|
+
* The Source of a mutation that is a declared `Write`, with no handler: the
|
|
818
|
+
* input bound to the write lands through `writer`, and the row as written
|
|
819
|
+
* answers as a patch (a deletion as `deleted`). An update writes only the
|
|
820
|
+
* keys the client named, when it named some, and fails for a row that is not
|
|
821
|
+
* there; an insert of an id already taken is refused as taken, alike
|
|
822
|
+
* whatever the row holds, unless the writer's ledger records this operation
|
|
823
|
+
* as the insert that made it (a retry), answered with that row; a delete of
|
|
824
|
+
* a row already gone succeeds. A row that moved past the revision the write
|
|
825
|
+
* `expect`s is refused as a conflict, and one that does not hold its `when`
|
|
826
|
+
* as unmet; a write with a `when` needs a writer that checks it
|
|
827
|
+
* (`preconditions`), and is refused here without one.
|
|
828
|
+
*/
|
|
829
|
+
write: <P = unknown, R = never, Name extends string = string, Input = unknown>(mutation: MutationDescriptor<Name, Input, {}, any> & {
|
|
830
|
+
readonly write: AnyWrite;
|
|
831
|
+
}, writer: EntityWriter<P, R>) => MutationSource<P, R>;
|
|
832
|
+
query: <P = unknown, R = never, Input = unknown>(query: QueryDescriptor<string, Input, ConnectionSpec>, run: (context: {
|
|
833
|
+
readonly input: Input;
|
|
834
|
+
readonly window: QueryWindow;
|
|
835
|
+
readonly principal: P;
|
|
836
|
+
/** As `EntitySourceContext.viewer`. */
|
|
837
|
+
readonly viewer?: Option.Option<EntityRef> | undefined;
|
|
838
|
+
readonly select?: RelationRequirement | undefined;
|
|
839
|
+
}) => Effect.Effect<QueryPage, RemoteServerError, R>) => QuerySource<P, R>;
|
|
840
|
+
/**
|
|
841
|
+
* Reads through `source` as the read handlers and the live hub do: only the
|
|
842
|
+
* asked fields the source declares and its `authorize` allows, each record
|
|
843
|
+
* through its `filter` and holding no other field. None when the principal
|
|
844
|
+
* may read none of the fields asked. What a live source of its own reads
|
|
845
|
+
* with, so it sends no more than a read would.
|
|
846
|
+
*/
|
|
847
|
+
readAs: typeof readAs;
|
|
848
|
+
/**
|
|
849
|
+
* The fields of `fields` that `readAs` reads for `principal`: those the
|
|
850
|
+
* source declares and its `authorize` allows, in the order asked. Asks
|
|
851
|
+
* nothing of the store.
|
|
852
|
+
*/
|
|
853
|
+
allowedFields: typeof allowedFields;
|
|
854
|
+
/** Streams live entity patches for a client's live requirements. */
|
|
855
|
+
live: <P = unknown, R = never>(entity: EntityName, options: {
|
|
856
|
+
readonly subscribe: LiveSource<P, R>['subscribe'];
|
|
857
|
+
}) => LiveSource<P, R>;
|
|
858
|
+
/**
|
|
859
|
+
* A `LiveHub` over entity sources. Pass it to `handlers` as `live`, and every
|
|
860
|
+
* mutation's answered patches and deletions are published to it; call
|
|
861
|
+
* `hub.changed(ref, fields)` yourself only for a write that is not a
|
|
862
|
+
* mutation (a database trigger, a job). Each subscriber that selects any of
|
|
863
|
+
* those fields receives them, re-read through the entity source under its
|
|
864
|
+
* own principal.
|
|
865
|
+
*/
|
|
866
|
+
liveHub: typeof liveHub;
|
|
867
|
+
/**
|
|
868
|
+
* The server: its sources by name. `viewer` says who asks, as a row
|
|
869
|
+
* (`principal => Option.some(Remote.ref(User, principal.id))`), or none for
|
|
870
|
+
* a visitor: what a declared write's `Expr.viewer` sets. A server
|
|
871
|
+
* registering such an insert without one is refused here.
|
|
872
|
+
*
|
|
873
|
+
* `clockSkew` is how far from this server's clock a client's time (the
|
|
874
|
+
* `now` a write is sent with, when the reader acted) may be and still be
|
|
875
|
+
* the write's time: 60 seconds unless given, and `0` to never take it. A
|
|
876
|
+
* time beyond it is replaced by the server's own, and reported as
|
|
877
|
+
* `ClockSkewed`. It bounds how far a client can backdate or postdate a row.
|
|
878
|
+
*/
|
|
879
|
+
make: <P = unknown, R = never>(config: {
|
|
880
|
+
readonly entities: readonly EntitySource<P, R>[];
|
|
881
|
+
readonly mutations?: readonly MutationSource<P, R>[];
|
|
882
|
+
readonly queries?: readonly QuerySource<P, R>[];
|
|
883
|
+
readonly live?: readonly LiveSource<P, R>[];
|
|
884
|
+
readonly viewer?: ((principal: P) => Option.Option<EntityRef>) | undefined;
|
|
885
|
+
readonly clockSkew?: Duration.Input | undefined;
|
|
886
|
+
}) => ServerDefinition<P, R>;
|
|
887
|
+
/**
|
|
888
|
+
* Checks every source name against the declared domain, so an undeclared
|
|
889
|
+
* entity/query/mutation fails at startup rather than returning nothing at
|
|
890
|
+
* call time.
|
|
891
|
+
*/
|
|
892
|
+
validate: (domain: RemoteDescriptor, server: ServerDefinition<any, any>) => void;
|
|
893
|
+
/**
|
|
894
|
+
* Reads entity requirements through the entity sources, level by level,
|
|
895
|
+
* following relations as `FoldkitRemoteRead` does. Shared by the read
|
|
896
|
+
* handler and the query handler's payload: a query page's items are just
|
|
897
|
+
* requirements the page names, so one response carries both.
|
|
898
|
+
*/
|
|
899
|
+
readHelper: <P, R>(server: ServerDefinition<P, R>, principal: P, options: HandlerOptions<P, R>, requests: ReadonlyArray<Requirement>) => Effect.Effect<{
|
|
900
|
+
readonly entities: Array<{
|
|
901
|
+
readonly entity: string;
|
|
902
|
+
readonly id: string;
|
|
903
|
+
readonly values: Record<string, unknown>;
|
|
904
|
+
}>;
|
|
905
|
+
readonly settled: Array<{
|
|
906
|
+
readonly entity: string;
|
|
907
|
+
readonly id: string;
|
|
908
|
+
readonly fields: Array<string>;
|
|
909
|
+
}>;
|
|
910
|
+
}, RemoteReadError, R>;
|
|
911
|
+
/**
|
|
912
|
+
* Answers one JSON request through `handlers`: what an HTTP endpoint, a
|
|
913
|
+
* worker or a server in the page calls with the body it received, parsed.
|
|
914
|
+
* The request and its payload are decoded by the protocol's own schemas
|
|
915
|
+
* before a handler sees them, so an operation name is one of Remote's three
|
|
916
|
+
* and nothing else. A body that is not a request is a 400; a caller who
|
|
917
|
+
* could not be told a 401; a refusal of who is asking a 403; a mutation's
|
|
918
|
+
* declared refusal a 422, or a 409 when it is `Refusal.taken`; a handler's
|
|
919
|
+
* failure a 500 with its message; a defect a 500 that says nothing of it,
|
|
920
|
+
* its cause reported as a `ServerDefect` (`Diagnostics`, by default the log).
|
|
921
|
+
* `Remote.json` and `Remote.http` are the other end.
|
|
922
|
+
*/
|
|
923
|
+
answer: <R>(handlers: RemoteRpcClient<R>, body: unknown) => Effect.Effect<{
|
|
924
|
+
readonly status: 200 | 400 | 401 | 403 | 409 | 422 | 500;
|
|
925
|
+
readonly body: RemoteJsonAnswer;
|
|
926
|
+
}, never, R>;
|
|
927
|
+
/**
|
|
928
|
+
* Compiles the server into Remote's RPC handlers, answering as `principal`:
|
|
929
|
+
* a value, or a Context key (`G.Principal`) read on each call, which
|
|
930
|
+
* authentication provides per request. Unknown entities, entities with no
|
|
931
|
+
* allowed fields, and unknown mutations return an error or nothing rather
|
|
932
|
+
* than leaking existence.
|
|
933
|
+
*/
|
|
934
|
+
handlers: <P, R, I = never>(server: ServerDefinition<P, R>, principal: P | Context.Key<I, P>, options?: HandlerOptions<P, R>) => RemoteRpcClient<R | I>;
|
|
935
|
+
};
|
|
936
|
+
export { WriteRequirement as A, assertSupported$1 as B, RemoteInvalid as C, RemoteUnmet as D, RemoteTaken as E, PublishFailed as F, supported as H, RemoteServerDiagnostic as I, ServerDefect as L, exprContext as M, AnswerUnread as N, RowRequirement as O, ClockSkewed as P, QueryEvaluateError as R, ReadPlan as S, RemoteServerError as T, evaluate$1 as V, MutationOutcome as _, EntityWriter as a, QueryPage as b, LiveQuery as c, MemoryBackend as d, MemoryConfig as f, MemoryStore as g, MemoryServed as h, EntitySourceContext as i, WriteWhen as j, ServerDefinition as k, LiveSource as l, MemoryRows as m, EntityRecord as n, HandlerOptions as o, MemoryReadable as p, EntitySource as r, LiveHub as s, ConnectionChange as t, MemoryAnswering as u, MutationRefused as v, RemoteServer as w, QuerySource as x, MutationSource as y, Row as z };
|
|
937
|
+
//# sourceMappingURL=index-BnaRbvjr.d.mts.map
|