@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/src/push.ts CHANGED
@@ -60,7 +60,10 @@ import {
60
60
  readCandidateRows,
61
61
  serveGateRefusal,
62
62
  } from './storage';
63
- import { StorageConstraintError } from './storage-errors';
63
+ import {
64
+ ClosedCommitConstraintError,
65
+ StorageConstraintError,
66
+ } from './storage-errors';
64
67
  import { transactionQuery } from './storage-query';
65
68
  import { serveNotReadyError } from './readiness';
66
69
  import type {
@@ -1849,6 +1852,11 @@ export async function processPushOperationsWithTrace(
1849
1852
  *
1850
1853
  * `outbox` lists every commit of the request in the same order as
1851
1854
  * `commits`; it carries the §6.3.2 sequences and the §9 settlement.
1855
+ *
1856
+ * A storage may write a closed commit with the request's later statements
1857
+ * (PostgreSQL). When a relational constraint fails there, no commit can be
1858
+ * rejected alone: the request rolls back and runs once more with every
1859
+ * commit written before it closes, as a client retry would (§6.4).
1852
1860
  */
1853
1861
  export async function processPushCommitsWithTrace(
1854
1862
  ctx: SyncRequestContext,
@@ -1858,6 +1866,35 @@ export async function processPushCommitsWithTrace(
1858
1866
  commits: readonly PushRequestCommit[],
1859
1867
  wireSchema: CompiledSchema = schema,
1860
1868
  outbox?: OutboxSettlement,
1869
+ ): Promise<ProcessedPushCommit[]> {
1870
+ const apply = (closeEagerly: boolean) =>
1871
+ applyPushCommits(
1872
+ ctx,
1873
+ schema,
1874
+ resolved,
1875
+ clientId,
1876
+ commits,
1877
+ wireSchema,
1878
+ outbox,
1879
+ closeEagerly,
1880
+ );
1881
+ try {
1882
+ return await apply(false);
1883
+ } catch (error) {
1884
+ if (!(error instanceof ClosedCommitConstraintError)) throw error;
1885
+ return apply(true);
1886
+ }
1887
+ }
1888
+
1889
+ async function applyPushCommits(
1890
+ ctx: SyncRequestContext,
1891
+ schema: CompiledSchema,
1892
+ resolved: ResolvedScopes,
1893
+ clientId: string,
1894
+ commits: readonly PushRequestCommit[],
1895
+ wireSchema: CompiledSchema,
1896
+ outbox: OutboxSettlement | undefined,
1897
+ closeEagerly: boolean,
1861
1898
  ): Promise<ProcessedPushCommit[]> {
1862
1899
  const { partition } = ctx;
1863
1900
  const blobCtx: BlobApplyContext = {
@@ -1936,6 +1973,7 @@ export async function processPushCommitsWithTrace(
1936
1973
  })),
1937
1974
  schema.version,
1938
1975
  outbox,
1976
+ closeEagerly ? { closeEagerly } : undefined,
1939
1977
  );
1940
1978
  // RFC 0007: the gate is evaluated while the partition lock is held, so
1941
1979
  // the migration check and the writes share one transaction and no
@@ -569,13 +569,16 @@ export function upsertValues(
569
569
 
570
570
  /**
571
571
  * Upsert statement text (bind with `upsertValues`). PostgreSQL takes `rows`
572
- * rows in one statement, bound as consecutive `upsertValues` lists; their
573
- * row ids must be distinct.
572
+ * rows in one statement, bound as consecutive `upsertValues` lists from
573
+ * parameter `offset + 1` on; their row ids must be distinct. A JSONB column
574
+ * binds as text before the JSONB cast, so a driver that JSON-encodes a string
575
+ * bound to `jsonb` (Bun.sql) cannot store the document as a JSON string.
574
576
  */
575
577
  export function upsertSql(
576
578
  table: CompiledTable,
577
579
  dialect: RelationalDialect,
578
580
  rows = 1,
581
+ offset = 0,
579
582
  ): string {
580
583
  const names = tableColumnNames(table);
581
584
  const quoted = names.map((name) => quoteIdent(name)).join(', ');
@@ -585,7 +588,7 @@ export function upsertSql(
585
588
  : Array.from(
586
589
  { length: rows },
587
590
  (_, row) =>
588
- `(${names.map((_, column) => `$${row * names.length + column + 1}`).join(',')})`,
591
+ `(${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(',')})`,
589
592
  ).join(',');
590
593
  const updates = names
591
594
  .slice(2) // partition + row id are the conflict key
@@ -13,6 +13,20 @@ export class StorageConstraintError extends Error {
13
13
  }
14
14
  }
15
15
 
16
+ /**
17
+ * A relational constraint failed on the writes of push commits that had
18
+ * already closed, which a storage defers to its next statement (§6.4). The
19
+ * transaction is aborted and no commit can be rejected alone, so the push
20
+ * layer reruns the request with `closeEagerly`.
21
+ */
22
+ export class ClosedCommitConstraintError extends Error {
23
+ override readonly name = 'ClosedCommitConstraintError';
24
+
25
+ constructor(cause: unknown) {
26
+ super('a closed commit violates a relational constraint', { cause });
27
+ }
28
+ }
29
+
16
30
  /** Stable, privacy-safe failures for trusted server storage queries. */
17
31
  export type StorageQueryErrorCode =
18
32
  | 'sync.storage.schema_migration_pending'
package/src/storage.ts CHANGED
@@ -118,6 +118,16 @@ export interface PushApplyCommit {
118
118
  }[];
119
119
  }
120
120
 
121
+ /** How `preparePushApply` closes the request's commits. */
122
+ export interface PushApplyOptions {
123
+ /**
124
+ * Write each commit behind its savepoint before it closes. The push layer
125
+ * sets it on the rerun after `ClosedCommitConstraintError`; a storage that
126
+ * never defers a closed commit's writes ignores it.
127
+ */
128
+ readonly closeEagerly?: boolean;
129
+ }
130
+
121
131
  /** The outbox position of one pushed commit (§6.3.2). */
122
132
  export interface OutboxSequence {
123
133
  readonly outboxId: string;
@@ -825,6 +835,7 @@ export interface StorageTransaction {
825
835
  commits: readonly PushApplyCommit[],
826
836
  runningSchemaVersion: number,
827
837
  outbox?: OutboxSettlement,
838
+ options?: PushApplyOptions,
828
839
  ): Promise<PreparedPushApply>;
829
840
  /**
830
841
  * Reject the request's current commit while the push-apply serialization
@@ -846,7 +857,11 @@ export interface StorageTransaction {
846
857
  context?: { readonly opIndex: number },
847
858
  ): Promise<void>;
848
859
  deleteRow(table: string, rowId: string): Promise<void>;
849
- /** Allocates the next per-partition commitSeq and appends the commit. */
860
+ /**
861
+ * Allocates the next per-partition commitSeq and appends the commit. A
862
+ * storage may hold the append back with the commit's rows until a later
863
+ * statement of the transaction.
864
+ */
850
865
  appendCommit(commit: NewCommit): Promise<number>;
851
866
  /**
852
867
  * Persist reaction rows in this authoritative transaction. Required when
@@ -861,10 +876,12 @@ export interface StorageTransaction {
861
876
  * by a watermark.
862
877
  *
863
878
  * The call closes the request's current push commit: the next write opens
864
- * the next commit's savepoint. PostgreSQL writes the request's results as
865
- * one statement at `commit()`. D1, whose transaction cannot read its own
866
- * staged writes across commits, flushes the commit's writes and this
867
- * result as one atomic batch here (§6.4).
879
+ * the next commit's savepoint. PostgreSQL holds the closed commit's rows,
880
+ * append and result back and writes them with the request's next
881
+ * statement; a relational constraint that fails there throws
882
+ * `ClosedCommitConstraintError` (§6.4). D1, whose transaction cannot read
883
+ * its own staged writes across commits, flushes the commit's writes and
884
+ * this result as one atomic batch here.
868
885
  */
869
886
  putPushResult(
870
887
  clientId: string,