@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/dist/validate.d.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
|
|
@@ -36,8 +37,9 @@ export type ValidateRow = Readonly<Record<string, RowValue>>;
|
|
|
36
37
|
export type ValidateOpKind = 'upsert' | 'delete';
|
|
37
38
|
/**
|
|
38
39
|
* One push operation as the validator sees it (§6.7). For an `upsert`,
|
|
39
|
-
* `row` is the post-merge, post-scope-strip row that will be written
|
|
40
|
-
*
|
|
40
|
+
* `row` is the post-merge, post-scope-strip row that will be written, with
|
|
41
|
+
* each server-owned column as stored (NULL on an insert), and `stored` is
|
|
42
|
+
* the prior stored row (or `undefined` on insert). For a
|
|
41
43
|
* `delete`, `row` is `undefined` and `stored` is the row about to be
|
|
42
44
|
* removed (a delete only reaches a validator when a stored row exists —
|
|
43
45
|
* an absent-row delete is an idempotent no-op that never validates, §6.2).
|
|
@@ -151,7 +153,7 @@ export type CommitValidator = (input: ValidateCommitInput) => void | Promise<voi
|
|
|
151
153
|
* inside and the push never completes, and on a pool-backed executor (`pg`,
|
|
152
154
|
* `Bun.sql`) it reads committed state without the staged writes, or waits
|
|
153
155
|
* forever once push transactions hold every pool connection. An authority
|
|
154
|
-
* read
|
|
156
|
+
* read goes through `read` instead.
|
|
155
157
|
*/
|
|
156
158
|
export interface ValidateContext {
|
|
157
159
|
/** Host-authenticated actor (§1.1) performing the write. */
|
|
@@ -161,15 +163,13 @@ export interface ValidateContext {
|
|
|
161
163
|
/** The context `authenticate` returned for this request (§1.1); absent without one. */
|
|
162
164
|
readonly context?: string;
|
|
163
165
|
/**
|
|
164
|
-
*
|
|
165
|
-
*
|
|
166
|
-
*
|
|
167
|
-
* PostgreSQL return the transaction's snapshot, including the operations
|
|
168
|
-
* staged before this one; D1 fails with
|
|
166
|
+
* The §6.8 candidate-state reader of the push transaction: it sees every
|
|
167
|
+
* operation staged before this one. `read.queryAuthoritative` runs a
|
|
168
|
+
* generated registered query on that transaction; D1 fails with
|
|
169
169
|
* `sync.storage.query_over_staged_writes` when the query reads a table the
|
|
170
170
|
* commit has written.
|
|
171
171
|
*/
|
|
172
|
-
readonly
|
|
172
|
+
readonly read: CommitValidationReader;
|
|
173
173
|
}
|
|
174
174
|
/**
|
|
175
175
|
* A per-table validation hook (§6.7). Called once per push operation on
|
|
@@ -180,14 +180,21 @@ export interface ValidateContext {
|
|
|
180
180
|
* `sync.constraint_violation` code (a validator SHOULD throw
|
|
181
181
|
* `ValidationRejection` to control the code). MUST NOT mutate the row.
|
|
182
182
|
*
|
|
183
|
+
* On an insert or update of a pushed commit or a registered command, the
|
|
184
|
+
* validator may return values for the table's server-owned columns; a column
|
|
185
|
+
* it omits keeps its value in `row`. A key that names no server-owned column,
|
|
186
|
+
* a value the column's type refuses, or a changed scope column on an update
|
|
187
|
+
* rejects the commit with `sync.constraint_violation`. The server ignores
|
|
188
|
+
* returned values on a delete, a rescope (§2.2) and a §6.11 cascade.
|
|
189
|
+
*
|
|
183
190
|
* The hook runs inside the push transaction. An authority read uses
|
|
184
|
-
* `ctx.queryAuthoritative`, which executes on that transaction; calling
|
|
191
|
+
* `ctx.read.queryAuthoritative`, which executes on that transaction; calling
|
|
185
192
|
* `ServerStorage.queryAuthoritative` from here deadlocks on a
|
|
186
193
|
* single-connection executor and reads committed state on a pool-backed one.
|
|
187
194
|
* A rule over sibling operations belongs in the whole-commit
|
|
188
195
|
* `CommitValidator` (§6.8).
|
|
189
196
|
*/
|
|
190
|
-
export type Validator = (op: ValidateOperation, ctx: ValidateContext) => void | Promise<void>;
|
|
197
|
+
export type Validator = (op: ValidateOperation, ctx: ValidateContext) => ValidateRow | void | Promise<ValidateRow | void>;
|
|
191
198
|
/** Table name → validator (§6.7). Absent tables are unvalidated. */
|
|
192
199
|
export type ValidatorRegistry = Readonly<Record<string, Validator>>;
|
|
193
200
|
/**
|
|
@@ -222,28 +229,3 @@ export declare class CommitAuthorizationRejection extends SyncError {
|
|
|
222
229
|
}
|
|
223
230
|
/** Build the column-keyed row object a validator inspects (§6.7). */
|
|
224
231
|
export declare function toValidateRow(columns: readonly RowColumn[], values: readonly RowValue[]): ValidateRow;
|
|
225
|
-
/** §6.12: the accepted upsert a server column hook completes. `row` is the
|
|
226
|
-
* merged row (present columns over stored values, crdt columns merged) with
|
|
227
|
-
* every server-owned column as stored, or NULL on an insert. */
|
|
228
|
-
export interface ServerColumnsInput {
|
|
229
|
-
readonly table: string;
|
|
230
|
-
readonly rowId: string;
|
|
231
|
-
readonly row: ValidateRow;
|
|
232
|
-
readonly stored: ValidateRow | undefined;
|
|
233
|
-
}
|
|
234
|
-
export interface ServerColumnsContext {
|
|
235
|
-
readonly actorId: string;
|
|
236
|
-
readonly partition: string;
|
|
237
|
-
readonly context?: string;
|
|
238
|
-
/** The §6.8 candidate-state reader of the push transaction. */
|
|
239
|
-
readonly read: CommitValidationReader;
|
|
240
|
-
}
|
|
241
|
-
/**
|
|
242
|
-
* §6.12: returns values for the table's server-owned columns; a column it
|
|
243
|
-
* omits keeps its value in `row`. A key that names no server-owned column, a
|
|
244
|
-
* value the column's type refuses, or a changed scope column on an update
|
|
245
|
-
* rejects the commit with `sync.constraint_violation`, like any other throw
|
|
246
|
-
* that is not a {@link ValidationRejection}.
|
|
247
|
-
*/
|
|
248
|
-
export type ServerColumnsHook = (input: ServerColumnsInput, ctx: ServerColumnsContext) => ValidateRow | Promise<ValidateRow>;
|
|
249
|
-
export type ServerColumnsRegistry = Readonly<Record<string, ServerColumnsHook>>;
|
package/dist/validate.js
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
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@syncular/server",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.96.0",
|
|
4
4
|
"description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "Benjamin Kniffler",
|
|
@@ -68,7 +68,7 @@
|
|
|
68
68
|
"verify:node": "cd ../.. && bun build ./packages/server/test/sqlite-runtime/verify-node.mjs --target=node --conditions=bun --outfile=./packages/server/.verify-node.built.mjs && node ./packages/server/.verify-node.built.mjs"
|
|
69
69
|
},
|
|
70
70
|
"dependencies": {
|
|
71
|
-
"@syncular/core": "0.
|
|
71
|
+
"@syncular/core": "0.96.0"
|
|
72
72
|
},
|
|
73
73
|
"devDependencies": {
|
|
74
74
|
"@electric-sql/pglite": "^0.5.4"
|
package/src/context.ts
CHANGED
|
@@ -25,11 +25,7 @@ import type {
|
|
|
25
25
|
ServerStorage,
|
|
26
26
|
StoredCommit,
|
|
27
27
|
} from './storage';
|
|
28
|
-
import type {
|
|
29
|
-
CommitValidator,
|
|
30
|
-
ServerColumnsRegistry,
|
|
31
|
-
ValidatorRegistry,
|
|
32
|
-
} from './validate';
|
|
28
|
+
import type { CommitValidator, ValidatorRegistry } from './validate';
|
|
33
29
|
|
|
34
30
|
/** SSP2 body content type (§1.1). */
|
|
35
31
|
export const SSP2_CONTENT_TYPE = 'application/vnd.syncular.sync.v2';
|
|
@@ -124,12 +120,6 @@ export interface ServerLimits {
|
|
|
124
120
|
* bound gets an image of its own.
|
|
125
121
|
*/
|
|
126
122
|
readonly maxImageSegmentBytes: number;
|
|
127
|
-
/**
|
|
128
|
-
* Segment puts one pull keeps in flight. The pull scans and encodes its
|
|
129
|
-
* pages in order and stores up to this many at once, so it holds this
|
|
130
|
-
* many encoded segments in memory.
|
|
131
|
-
*/
|
|
132
|
-
readonly maxConcurrentSegmentPuts: number;
|
|
133
123
|
}
|
|
134
124
|
|
|
135
125
|
export const DEFAULT_LIMITS: ServerLimits = {
|
|
@@ -146,9 +136,6 @@ export const DEFAULT_LIMITS: ServerLimits = {
|
|
|
146
136
|
maxLiveSectionBytes: 16 * 1024 * 1024,
|
|
147
137
|
// §5.3 DECISION (2026-11-17): a client holds about three images at once.
|
|
148
138
|
maxImageSegmentBytes: 32 * 1024 * 1024,
|
|
149
|
-
// A Workers invocation holds six connections open at once, and an R2 put
|
|
150
|
-
// uses one; past six the runtime queues the put.
|
|
151
|
-
maxConcurrentSegmentPuts: 6,
|
|
152
139
|
};
|
|
153
140
|
|
|
154
141
|
/** Receives applied commits for realtime fanout (§8.2). */
|
|
@@ -200,19 +187,13 @@ export interface SyncServerConfig {
|
|
|
200
187
|
* builds no validator context — zero cost. Present ⇒ each push operation
|
|
201
188
|
* on a listed table runs its validator after decode + §3.4 scope
|
|
202
189
|
* authorization, inside the commit transaction; a throw rejects the
|
|
203
|
-
* whole commit atomically (§6.4) with the host code (§6.3).
|
|
190
|
+
* whole commit atomically (§6.4) with the host code (§6.3). On an insert
|
|
191
|
+
* or update the validator may return values of the table's server-owned
|
|
192
|
+
* columns, which are stored and fanned out in the same commit. Kept a host
|
|
204
193
|
* callback (like `resolveScopes`) — business rules live in the host
|
|
205
194
|
* process, never on the wire.
|
|
206
195
|
*/
|
|
207
196
|
readonly validators?: ValidatorRegistry;
|
|
208
|
-
/**
|
|
209
|
-
* §6.12 per-table server column hooks (`table` → hook). Each accepted
|
|
210
|
-
* upsert on a listed table runs its hook inside the push transaction,
|
|
211
|
-
* after §3.4 authorization and before §6.7 validation; the returned values
|
|
212
|
-
* of the table's server-owned columns are stored and fanned out in the
|
|
213
|
-
* same commit.
|
|
214
|
-
*/
|
|
215
|
-
readonly serverColumns?: ServerColumnsRegistry;
|
|
216
197
|
/**
|
|
217
198
|
* §6.8 whole-commit validator. When present, the storage serializes this
|
|
218
199
|
* partition before operation reads/writes, then invokes the callback once
|
package/src/errors.ts
CHANGED
|
@@ -234,6 +234,14 @@ export const ERROR_CATALOG: Readonly<Record<string, ErrorCatalogEntry>> = {
|
|
|
234
234
|
recommendedAction: 'forceResync',
|
|
235
235
|
httpStatus: 404,
|
|
236
236
|
},
|
|
237
|
+
// §1.6: a response still building at the 300 s build deadline. In-band
|
|
238
|
+
// after its header frames, HTTP 503 before them.
|
|
239
|
+
'sync.segment_build_timeout': {
|
|
240
|
+
category: 'internal',
|
|
241
|
+
retryable: true,
|
|
242
|
+
recommendedAction: 'retryLater',
|
|
243
|
+
httpStatus: 503,
|
|
244
|
+
},
|
|
237
245
|
'sync.segment_expired': {
|
|
238
246
|
category: 'not-found',
|
|
239
247
|
retryable: true,
|
package/src/frame-bytes.ts
CHANGED
|
@@ -71,6 +71,7 @@ function wrapperFor(frame: ResponseFrame): {
|
|
|
71
71
|
switch (frame.type) {
|
|
72
72
|
case 'RESP_HEADER':
|
|
73
73
|
return { frames: [frame], index: 0 };
|
|
74
|
+
case 'KEEPALIVE':
|
|
74
75
|
case 'LEASE':
|
|
75
76
|
// §7.3.2: LEASE rides immediately after RESP_HEADER.
|
|
76
77
|
return { frames: [stubHeader(), frame], index: 1 };
|