@syncular/server 0.95.0 → 0.96.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 +6 -5
- package/dist/context.d.ts +4 -16
- package/dist/context.js +0 -3
- package/dist/errors.js +8 -0
- package/dist/frame-bytes.js +1 -0
- package/dist/handler.d.ts +20 -2
- package/dist/handler.js +195 -58
- package/dist/postgres-storage.d.ts +3 -2
- package/dist/postgres-storage.js +18 -2
- package/dist/pull.d.ts +2 -2
- package/dist/pull.js +12 -11
- package/dist/push.js +41 -77
- package/dist/realtime.d.ts +5 -11
- package/dist/realtime.js +10 -23
- package/dist/relational-rows.d.ts +4 -2
- package/dist/relational-rows.js +8 -3
- package/dist/schema-window.js +2 -2
- package/dist/schema.d.ts +2 -2
- package/dist/schema.js +2 -2
- package/dist/sqlite-dialect.d.ts +3 -1
- package/dist/sqlite-dialect.js +37 -5
- package/dist/storage.d.ts +12 -0
- package/dist/validate.d.ts +21 -39
- package/dist/validate.js +4 -3
- package/package.json +2 -2
- package/src/context.ts +4 -23
- package/src/errors.ts +8 -0
- package/src/frame-bytes.ts +1 -0
- package/src/handler.ts +251 -72
- package/src/postgres-storage.ts +32 -6
- package/src/pull.ts +22 -12
- package/src/push.ts +51 -129
- package/src/realtime.ts +10 -22
- package/src/relational-rows.ts +10 -3
- package/src/schema-window.ts +2 -2
- package/src/schema.ts +4 -4
- package/src/sqlite-dialect.ts +47 -6
- package/src/storage.ts +13 -0
- package/src/validate.ts +21 -48
package/src/validate.ts
CHANGED
|
@@ -5,9 +5,10 @@
|
|
|
5
5
|
* row-codec decode (§6.1) and the §3.4 scope authorization, INSIDE the
|
|
6
6
|
* commit transaction, once per operation. It is the seam for business
|
|
7
7
|
* rules that scopes cannot express ("title ≤ 200 chars", "amount ≥ 0",
|
|
8
|
-
* "status ∈ {…}")
|
|
9
|
-
* atomically (§6.4) with a
|
|
10
|
-
* in its rejection record
|
|
8
|
+
* "status ∈ {…}") and for the values of server-owned columns. A throw (or
|
|
9
|
+
* rejected promise) rejects the whole commit atomically (§6.4) with a
|
|
10
|
+
* host-defined code the client surfaces unchanged in its rejection record
|
|
11
|
+
* (§6.3).
|
|
11
12
|
*
|
|
12
13
|
* The feature is OFF by default (no `validators` on the config): the push
|
|
13
14
|
* path pays only an `undefined` check per operation and builds no context
|
|
@@ -55,8 +56,9 @@ export type ValidateOpKind = 'upsert' | 'delete';
|
|
|
55
56
|
|
|
56
57
|
/**
|
|
57
58
|
* One push operation as the validator sees it (§6.7). For an `upsert`,
|
|
58
|
-
* `row` is the post-merge, post-scope-strip row that will be written
|
|
59
|
-
*
|
|
59
|
+
* `row` is the post-merge, post-scope-strip row that will be written, with
|
|
60
|
+
* each server-owned column as stored (NULL on an insert), and `stored` is
|
|
61
|
+
* the prior stored row (or `undefined` on insert). For a
|
|
60
62
|
* `delete`, `row` is `undefined` and `stored` is the row about to be
|
|
61
63
|
* removed (a delete only reaches a validator when a stored row exists —
|
|
62
64
|
* an absent-row delete is an idempotent no-op that never validates, §6.2).
|
|
@@ -188,7 +190,7 @@ export type CommitValidator = (
|
|
|
188
190
|
* inside and the push never completes, and on a pool-backed executor (`pg`,
|
|
189
191
|
* `Bun.sql`) it reads committed state without the staged writes, or waits
|
|
190
192
|
* forever once push transactions hold every pool connection. An authority
|
|
191
|
-
* read
|
|
193
|
+
* read goes through `read` instead.
|
|
192
194
|
*/
|
|
193
195
|
export interface ValidateContext {
|
|
194
196
|
/** Host-authenticated actor (§1.1) performing the write. */
|
|
@@ -198,17 +200,13 @@ export interface ValidateContext {
|
|
|
198
200
|
/** The context `authenticate` returned for this request (§1.1); absent without one. */
|
|
199
201
|
readonly context?: string;
|
|
200
202
|
/**
|
|
201
|
-
*
|
|
202
|
-
*
|
|
203
|
-
*
|
|
204
|
-
* PostgreSQL return the transaction's snapshot, including the operations
|
|
205
|
-
* staged before this one; D1 fails with
|
|
203
|
+
* The §6.8 candidate-state reader of the push transaction: it sees every
|
|
204
|
+
* operation staged before this one. `read.queryAuthoritative` runs a
|
|
205
|
+
* generated registered query on that transaction; D1 fails with
|
|
206
206
|
* `sync.storage.query_over_staged_writes` when the query reads a table the
|
|
207
207
|
* commit has written.
|
|
208
208
|
*/
|
|
209
|
-
readonly
|
|
210
|
-
query: AuthoritativeQueryRequest,
|
|
211
|
-
) => Promise<AuthoritativeQueryResult>;
|
|
209
|
+
readonly read: CommitValidationReader;
|
|
212
210
|
}
|
|
213
211
|
|
|
214
212
|
/**
|
|
@@ -220,8 +218,15 @@ export interface ValidateContext {
|
|
|
220
218
|
* `sync.constraint_violation` code (a validator SHOULD throw
|
|
221
219
|
* `ValidationRejection` to control the code). MUST NOT mutate the row.
|
|
222
220
|
*
|
|
221
|
+
* On an insert or update of a pushed commit or a registered command, the
|
|
222
|
+
* validator may return values for the table's server-owned columns; a column
|
|
223
|
+
* it omits keeps its value in `row`. A key that names no server-owned column,
|
|
224
|
+
* a value the column's type refuses, or a changed scope column on an update
|
|
225
|
+
* rejects the commit with `sync.constraint_violation`. The server ignores
|
|
226
|
+
* returned values on a delete, a rescope (§2.2) and a §6.11 cascade.
|
|
227
|
+
*
|
|
223
228
|
* The hook runs inside the push transaction. An authority read uses
|
|
224
|
-
* `ctx.queryAuthoritative`, which executes on that transaction; calling
|
|
229
|
+
* `ctx.read.queryAuthoritative`, which executes on that transaction; calling
|
|
225
230
|
* `ServerStorage.queryAuthoritative` from here deadlocks on a
|
|
226
231
|
* single-connection executor and reads committed state on a pool-backed one.
|
|
227
232
|
* A rule over sibling operations belongs in the whole-commit
|
|
@@ -230,7 +235,7 @@ export interface ValidateContext {
|
|
|
230
235
|
export type Validator = (
|
|
231
236
|
op: ValidateOperation,
|
|
232
237
|
ctx: ValidateContext,
|
|
233
|
-
) => void | Promise<void>;
|
|
238
|
+
) => ValidateRow | void | Promise<ValidateRow | void>;
|
|
234
239
|
|
|
235
240
|
/** Table name → validator (§6.7). Absent tables are unvalidated. */
|
|
236
241
|
export type ValidatorRegistry = Readonly<Record<string, Validator>>;
|
|
@@ -315,35 +320,3 @@ export function toValidateRow(
|
|
|
315
320
|
});
|
|
316
321
|
return row;
|
|
317
322
|
}
|
|
318
|
-
|
|
319
|
-
/** §6.12: the accepted upsert a server column hook completes. `row` is the
|
|
320
|
-
* merged row (present columns over stored values, crdt columns merged) with
|
|
321
|
-
* every server-owned column as stored, or NULL on an insert. */
|
|
322
|
-
export interface ServerColumnsInput {
|
|
323
|
-
readonly table: string;
|
|
324
|
-
readonly rowId: string;
|
|
325
|
-
readonly row: ValidateRow;
|
|
326
|
-
readonly stored: ValidateRow | undefined;
|
|
327
|
-
}
|
|
328
|
-
|
|
329
|
-
export interface ServerColumnsContext {
|
|
330
|
-
readonly actorId: string;
|
|
331
|
-
readonly partition: string;
|
|
332
|
-
readonly context?: string;
|
|
333
|
-
/** The §6.8 candidate-state reader of the push transaction. */
|
|
334
|
-
readonly read: CommitValidationReader;
|
|
335
|
-
}
|
|
336
|
-
|
|
337
|
-
/**
|
|
338
|
-
* §6.12: returns values for the table's server-owned columns; a column it
|
|
339
|
-
* omits keeps its value in `row`. A key that names no server-owned column, a
|
|
340
|
-
* value the column's type refuses, or a changed scope column on an update
|
|
341
|
-
* rejects the commit with `sync.constraint_violation`, like any other throw
|
|
342
|
-
* that is not a {@link ValidationRejection}.
|
|
343
|
-
*/
|
|
344
|
-
export type ServerColumnsHook = (
|
|
345
|
-
input: ServerColumnsInput,
|
|
346
|
-
ctx: ServerColumnsContext,
|
|
347
|
-
) => ValidateRow | Promise<ValidateRow>;
|
|
348
|
-
|
|
349
|
-
export type ServerColumnsRegistry = Readonly<Record<string, ServerColumnsHook>>;
|