@syncular/server 0.81.0 → 0.82.1

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/push.d.ts CHANGED
@@ -77,5 +77,10 @@ export declare function processPushOperationsWithTrace(ctx: SyncRequestContext,
77
77
  *
78
78
  * `outbox` lists every commit of the request in the same order as
79
79
  * `commits`; it carries the §6.3.2 sequences and the §9 settlement.
80
+ *
81
+ * A storage may write a closed commit with the request's later statements
82
+ * (PostgreSQL). When a relational constraint fails there, no commit can be
83
+ * rejected alone: the request rolls back and runs once more with every
84
+ * commit written before it closes, as a client retry would (§6.4).
80
85
  */
81
86
  export declare function processPushCommitsWithTrace(ctx: SyncRequestContext, schema: CompiledSchema, resolved: ResolvedScopes, clientId: string, commits: readonly PushRequestCommit[], wireSchema?: CompiledSchema, outbox?: OutboxSettlement): Promise<ProcessedPushCommit[]>;
package/dist/push.js CHANGED
@@ -27,7 +27,7 @@ import { prepareReactions, toNewReactions, } from './reactions.js';
27
27
  import { authorizeWrite, renderScopeValue, storedScopesForRow } from './scopes.js';
28
28
  import { decodeColumnVersions, encodeColumnVersions } from './relational-rows.js';
29
29
  import { commitDeleteFloor, readCandidateRows, serveGateRefusal, } from './storage.js';
30
- import { StorageConstraintError } from './storage-errors.js';
30
+ import { ClosedCommitConstraintError, StorageConstraintError, } from './storage-errors.js';
31
31
  import { transactionQuery } from './storage-query.js';
32
32
  import { serveNotReadyError } from './readiness.js';
33
33
  import { CommitAuthorizationRejection, CommitValidationRejection, toValidateRow, ValidationRejection, } from './validate.js';
@@ -1201,8 +1201,24 @@ export async function processPushOperationsWithTrace(ctx, schema, resolved, clie
1201
1201
  *
1202
1202
  * `outbox` lists every commit of the request in the same order as
1203
1203
  * `commits`; it carries the §6.3.2 sequences and the §9 settlement.
1204
+ *
1205
+ * A storage may write a closed commit with the request's later statements
1206
+ * (PostgreSQL). When a relational constraint fails there, no commit can be
1207
+ * rejected alone: the request rolls back and runs once more with every
1208
+ * commit written before it closes, as a client retry would (§6.4).
1204
1209
  */
1205
1210
  export async function processPushCommitsWithTrace(ctx, schema, resolved, clientId, commits, wireSchema = schema, outbox) {
1211
+ const apply = (closeEagerly) => applyPushCommits(ctx, schema, resolved, clientId, commits, wireSchema, outbox, closeEagerly);
1212
+ try {
1213
+ return await apply(false);
1214
+ }
1215
+ catch (error) {
1216
+ if (!(error instanceof ClosedCommitConstraintError))
1217
+ throw error;
1218
+ return apply(true);
1219
+ }
1220
+ }
1221
+ async function applyPushCommits(ctx, schema, resolved, clientId, commits, wireSchema, outbox, closeEagerly) {
1206
1222
  const { partition } = ctx;
1207
1223
  const blobCtx = {
1208
1224
  store: ctx.blobs,
@@ -1267,7 +1283,7 @@ export async function processPushCommitsWithTrace(ctx, schema, resolved, clientI
1267
1283
  const prepared = await tx.preparePushApply(clientId, commits.map((commit) => ({
1268
1284
  clientCommitId: commit.clientCommitId,
1269
1285
  ...(commit.targets === undefined ? {} : { targets: commit.targets }),
1270
- })), schema.version, outbox);
1286
+ })), schema.version, outbox, closeEagerly ? { closeEagerly } : undefined);
1271
1287
  // RFC 0007: the gate is evaluated while the partition lock is held, so
1272
1288
  // the migration check and the writes share one transaction and no
1273
1289
  // migration can interleave in between.
@@ -178,10 +178,12 @@ export declare function toSqlValue(column: RowColumn, value: RowValue, dialect:
178
178
  export declare function upsertValues(table: CompiledTable, partition: string, row: StoredRow, dialect: RelationalDialect): RowValue[];
179
179
  /**
180
180
  * Upsert statement text (bind with `upsertValues`). PostgreSQL takes `rows`
181
- * rows in one statement, bound as consecutive `upsertValues` lists; their
182
- * row ids must be distinct.
181
+ * rows in one statement, bound as consecutive `upsertValues` lists from
182
+ * parameter `offset + 1` on; their row ids must be distinct. A JSONB column
183
+ * binds as text before the JSONB cast, so a driver that JSON-encodes a string
184
+ * bound to `jsonb` (Bun.sql) cannot store the document as a JSON string.
183
185
  */
184
- export declare function upsertSql(table: CompiledTable, dialect: RelationalDialect, rows?: number): string;
186
+ export declare function upsertSql(table: CompiledTable, dialect: RelationalDialect, rows?: number, offset?: number): string;
185
187
  /**
186
188
  * SELECT one stored row. Aliased to the legacy record shape
187
189
  * (`row_id`/`server_version`/`scopes`/`payload`) so the existing
@@ -467,15 +467,17 @@ export function upsertValues(table, partition, row, dialect) {
467
467
  }
468
468
  /**
469
469
  * Upsert statement text (bind with `upsertValues`). PostgreSQL takes `rows`
470
- * rows in one statement, bound as consecutive `upsertValues` lists; their
471
- * row ids must be distinct.
470
+ * rows in one statement, bound as consecutive `upsertValues` lists from
471
+ * parameter `offset + 1` on; their row ids must be distinct. A JSONB column
472
+ * binds as text before the JSONB cast, so a driver that JSON-encodes a string
473
+ * bound to `jsonb` (Bun.sql) cannot store the document as a JSON string.
472
474
  */
473
- export function upsertSql(table, dialect, rows = 1) {
475
+ export function upsertSql(table, dialect, rows = 1, offset = 0) {
474
476
  const names = tableColumnNames(table);
475
477
  const quoted = names.map((name) => quoteIdent(name)).join(', ');
476
478
  const values = dialect === 'sqlite'
477
479
  ? `(${new Array(names.length).fill('?').join(',')})`
478
- : Array.from({ length: rows }, (_, row) => `(${names.map((_, column) => `$${row * names.length + column + 1}`).join(',')})`).join(',');
480
+ : Array.from({ length: rows }, (_, row) => `(${names.map((name, column) => `$${offset + row * names.length + column + 1}${name === SYNC_SCOPES_COLUMN || table.columns.some((c) => c.name === name && c.type === 'json') ? '::text::jsonb' : ''}`).join(',')})`).join(',');
479
481
  const updates = names
480
482
  .slice(2) // partition + row id are the conflict key
481
483
  .map((name) => `${quoteIdent(name)}=excluded.${quoteIdent(name)}`)
@@ -8,6 +8,16 @@ export declare class StorageConstraintError extends Error {
8
8
  readonly opIndex: number | undefined;
9
9
  constructor(cause: unknown, opIndex?: number);
10
10
  }
11
+ /**
12
+ * A relational constraint failed on the writes of push commits that had
13
+ * already closed, which a storage defers to its next statement (§6.4). The
14
+ * transaction is aborted and no commit can be rejected alone, so the push
15
+ * layer reruns the request with `closeEagerly`.
16
+ */
17
+ export declare class ClosedCommitConstraintError extends Error {
18
+ readonly name = "ClosedCommitConstraintError";
19
+ constructor(cause: unknown);
20
+ }
11
21
  /** Stable, privacy-safe failures for trusted server storage queries. */
12
22
  export type StorageQueryErrorCode = 'sync.storage.schema_migration_pending' | 'sync.storage.schema_migration_conflict' | 'sync.storage.schema_changed' | 'sync.storage.invalid_migration_budget' | 'sync.storage.scan_requires_scope' | 'sync.storage.index_not_found' | 'sync.storage.index_not_materialized' | 'sync.storage.index_value_count_mismatch' | 'sync.storage.invalid_limit' | 'sync.storage.prune_epoch_mismatch' | 'sync.storage.partition_unregistered' | 'sync.storage.invalid_prune_cursor' | 'sync.storage.checkpoint_not_declared' | 'sync.storage.checkpoint_unsupported' | 'sync.storage.checkpoint_fence_missing' | 'sync.storage.checkpoint_incomplete' | 'sync.storage.stored_layout_mismatch' | 'sync.storage.scope_patterns_changed' | 'sync.storage.scope_value_missing' | 'sync.storage.physical_layout_mismatch' | 'sync.storage.transaction_query_unsupported' | 'sync.storage.partition_lock_unsupported' | 'sync.storage.snapshot_unsupported' | 'sync.storage.query_over_staged_writes' | 'sync.storage.erase_unsupported' | 'sync.storage.invalid_erase_query';
13
23
  /**
@@ -11,6 +11,18 @@ export class StorageConstraintError extends Error {
11
11
  this.opIndex = opIndex;
12
12
  }
13
13
  }
14
+ /**
15
+ * A relational constraint failed on the writes of push commits that had
16
+ * already closed, which a storage defers to its next statement (§6.4). The
17
+ * transaction is aborted and no commit can be rejected alone, so the push
18
+ * layer reruns the request with `closeEagerly`.
19
+ */
20
+ export class ClosedCommitConstraintError extends Error {
21
+ name = 'ClosedCommitConstraintError';
22
+ constructor(cause) {
23
+ super('a closed commit violates a relational constraint', { cause });
24
+ }
25
+ }
14
26
  const STORAGE_QUERY_MESSAGES = {
15
27
  'sync.storage.schema_migration_pending': 'schema migration requires another invocation',
16
28
  'sync.storage.schema_migration_conflict': 'another schema migration target is already pending',
package/dist/storage.d.ts CHANGED
@@ -104,6 +104,15 @@ export interface PushApplyCommit {
104
104
  readonly rowIds: readonly string[];
105
105
  }[];
106
106
  }
107
+ /** How `preparePushApply` closes the request's commits. */
108
+ export interface PushApplyOptions {
109
+ /**
110
+ * Write each commit behind its savepoint before it closes. The push layer
111
+ * sets it on the rerun after `ClosedCommitConstraintError`; a storage that
112
+ * never defers a closed commit's writes ignores it.
113
+ */
114
+ readonly closeEagerly?: boolean;
115
+ }
107
116
  /** The outbox position of one pushed commit (§6.3.2). */
108
117
  export interface OutboxSequence {
109
118
  readonly outboxId: string;
@@ -655,7 +664,7 @@ export interface StorageTransaction {
655
664
  * 1 and 2 under the same lock, before the read of `persisted`. Those
656
665
  * writes precede every commit's savepoint, so no rejection discards them.
657
666
  */
658
- preparePushApply(clientId: string, commits: readonly PushApplyCommit[], runningSchemaVersion: number, outbox?: OutboxSettlement): Promise<PreparedPushApply>;
667
+ preparePushApply(clientId: string, commits: readonly PushApplyCommit[], runningSchemaVersion: number, outbox?: OutboxSettlement, options?: PushApplyOptions): Promise<PreparedPushApply>;
659
668
  /**
660
669
  * Reject the request's current commit while the push-apply serialization
661
670
  * lock is still held: discard every candidate write the commit staged since
@@ -669,7 +678,11 @@ export interface StorageTransaction {
669
678
  readonly opIndex: number;
670
679
  }): Promise<void>;
671
680
  deleteRow(table: string, rowId: string): Promise<void>;
672
- /** Allocates the next per-partition commitSeq and appends the commit. */
681
+ /**
682
+ * Allocates the next per-partition commitSeq and appends the commit. A
683
+ * storage may hold the append back with the commit's rows until a later
684
+ * statement of the transaction.
685
+ */
673
686
  appendCommit(commit: NewCommit): Promise<number>;
674
687
  /**
675
688
  * Persist reaction rows in this authoritative transaction. Required when
@@ -684,10 +697,12 @@ export interface StorageTransaction {
684
697
  * by a watermark.
685
698
  *
686
699
  * The call closes the request's current push commit: the next write opens
687
- * the next commit's savepoint. PostgreSQL writes the request's results as
688
- * one statement at `commit()`. D1, whose transaction cannot read its own
689
- * staged writes across commits, flushes the commit's writes and this
690
- * result as one atomic batch here (§6.4).
700
+ * the next commit's savepoint. PostgreSQL holds the closed commit's rows,
701
+ * append and result back and writes them with the request's next
702
+ * statement; a relational constraint that fails there throws
703
+ * `ClosedCommitConstraintError` (§6.4). D1, whose transaction cannot read
704
+ * its own staged writes across commits, flushes the commit's writes and
705
+ * this result as one atomic batch here.
691
706
  */
692
707
  putPushResult(clientId: string, clientCommitId: string, result: StoredPushResult, sequence?: OutboxSequence): Promise<void>;
693
708
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@syncular/server",
3
- "version": "0.81.0",
3
+ "version": "0.82.1",
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.81.0"
71
+ "@syncular/core": "0.82.1"
72
72
  },
73
73
  "devDependencies": {
74
74
  "@electric-sql/pglite": "^0.5.4"
@@ -127,10 +127,12 @@ export function prepareAuthoritativeQuery(
127
127
  throw new Error('registered query targets an unknown table');
128
128
  if (!table.materialize)
129
129
  throw new Error('registered query targets a non-materialized table');
130
+ // A `json` column reads as its JSON text on every storage: PostgreSQL
131
+ // stores it as JSONB, which its drivers would return parsed.
130
132
  return {
131
133
  start: relation.start,
132
134
  end: relation.end,
133
- text: `(SELECT ${table.columns.map((column) => quoteIdent(column.name)).join(', ')} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=?)${relation.alias === undefined ? ` AS ${quoteIdent(table.name)}` : ''}`,
135
+ text: `(SELECT ${table.columns.map((column) => (column.type === 'json' ? `CAST(${quoteIdent(column.name)} AS TEXT) AS ${quoteIdent(column.name)}` : quoteIdent(column.name))).join(', ')} FROM ${quoteIdent(table.name)} WHERE ${quoteIdent(SYNC_PARTITION_COLUMN)}=?)${relation.alias === undefined ? ` AS ${quoteIdent(table.name)}` : ''}`,
134
136
  };
135
137
  });
136
138
  const bound: (AuthoritativeQueryValue | typeof PARTITION_BIND)[] = [];
package/src/operations.ts CHANGED
@@ -282,19 +282,15 @@ function normalizeQueryRows(
282
282
  );
283
283
  }
284
284
  break;
285
- case 'json': {
286
- const json =
287
- typeof value === 'string' ? value : JSON.stringify(value);
288
- if (json === undefined) {
285
+ case 'json':
286
+ if (typeof value !== 'string') {
289
287
  throw syncError(
290
288
  'operation.query_failed',
291
289
  'registered query returned invalid JSON',
292
290
  );
293
291
  }
294
- JSON.parse(json);
295
- normalized[column.name] = json;
292
+ JSON.parse(value);
296
293
  break;
297
- }
298
294
  case 'bytes':
299
295
  case 'crdt': {
300
296
  const bytes =