@syncular/server 0.30.10 → 0.30.12

package/dist/errors.js

@@ -171,6 +171,12 @@ export const ERROR_CATALOG = {
         recommendedAction: 'retryLater',
         httpStatus: 500,
     },
+    'sync.storage_stale_read': {
+        category: 'internal',
+        retryable: false,
+        recommendedAction: 'inspectServer',
+        httpStatus: 503,
+    },
     'sync.schema_not_ready': {
         category: 'internal',
         retryable: true,

package/dist/events.d.ts

@@ -13,7 +13,7 @@
  * - Timestamps and durations come from the ctx clock where one exists, so
  *   the conformance virtual-clock discipline stays intact.
  */
-import type { WakeReason } from '@syncular/core';
+import type { ScopeMap, WakeReason } from '@syncular/core';
 /** One `POST /sync` request, emitted once per request after the response
  * bytes are fully produced (or the request was rejected up front). */
 export interface RequestHandledEvent {
@@ -141,6 +141,10 @@ export interface PullSubscriptionSummary {
     readonly status: 'active' | 'revoked' | 'reset';
     /** `none` for revoked/reset sections (no data half was produced). */
     readonly mode: 'bootstrap' | 'incremental' | 'none';
+    readonly requestedScopes: ScopeMap;
+    readonly effectiveScopes: ScopeMap;
+    readonly firstCommitSeq?: number;
+    readonly lastCommitSeq?: number;
     readonly fromCursor: number;
     readonly nextCursor: number;
     readonly commits: number;
@@ -154,6 +158,8 @@ export interface PullServedEvent {
     readonly partition: string;
     readonly actorId: string;
     readonly clientId: string;
+    readonly acceptedThrough: number;
+    readonly storageMaxCommitSeq: number;
     readonly subscriptions: readonly PullSubscriptionSummary[];
 }
 /** A direct segment download (§5.5), success or failure. */

package/dist/handler.js

@@ -335,8 +335,10 @@ async function* streamResponse(plan, ctx, schema, report) {
     }
     try {
         // Push half (§6): one PUSH_RESULT per PUSH_COMMIT, in request order.
+        let acceptedThrough = 0;
         for (const push of plan.pushes) {
             const processed = await processPushCommitWithTrace(ctx, compileSchema(ctx.schema), plan.resolved, plan.header.clientId, push, schema);
+            acceptedThrough = Math.max(acceptedThrough, processed.frame.commitSeq ?? 0);
             const frame = {
                 ...processed.frame,
                 results: processed.frame.results.map((result) => {
@@ -372,6 +374,8 @@ async function* streamResponse(plan, ctx, schema, report) {
             const summaries = events !== undefined ? [] : undefined;
             const limits = clampPullLimits(plan.pull);
             const maxSeq = await ctx.storage.getMaxCommitSeq(ctx.partition);
+            if (maxSeq < acceptedThrough)
+                throw syncError('sync.storage_stale_read', 'storage returned a commit sequence older than the accepted push; disable query caching for sync storage', JSON.stringify({ acceptedThrough, storageMaxCommitSeq: maxSeq }));
             const horizonSeq = await ctx.storage.getHorizonSeq(ctx.partition);
             const prepared = await prepareSections(ctx, schema, limits, plan.subscriptions, maxSeq, horizonSeq, plan.logEpoch);
             for (const [index, subscription] of plan.subscriptions.entries()) {
@@ -384,6 +388,9 @@ async function* streamResponse(plan, ctx, schema, report) {
                 let bootstrap = false;
                 let commits = 0;
                 let changes = 0;
+                let effectiveScopes = {};
+                let firstCommitSeq;
+                let lastCommitSeq;
                 let step = await section.next();
                 while (!step.done) {
                     const frame = step.value;
@@ -391,10 +398,13 @@ async function* streamResponse(plan, ctx, schema, report) {
                         if (frame.type === 'SUB_START') {
                             status = frame.status;
                             bootstrap = frame.bootstrap;
+                            effectiveScopes = frame.effectiveScopes;
                         }
                         else if (frame.type === 'COMMIT') {
                             commits += 1;
                             changes += frame.changes.length;
+                            firstCommitSeq ??= frame.commitSeq;
+                            lastCommitSeq = frame.commitSeq;
                         }
                     }
                     yield encodeResponseFrame(frame, plan.wireVersion);
@@ -412,6 +422,11 @@ async function* streamResponse(plan, ctx, schema, report) {
                             : bootstrap
                                 ? 'bootstrap'
                                 : 'incremental',
+                        requestedScopes: subscription.frame.scopes,
+                        effectiveScopes,
+                        ...(firstCommitSeq !== undefined && lastCommitSeq !== undefined
+                            ? { firstCommitSeq, lastCommitSeq }
+                            : {}),
                         fromCursor: subscription.frame.cursor,
                         nextCursor: step.value.nextCursor,
                         commits,
@@ -427,6 +442,8 @@ async function* streamResponse(plan, ctx, schema, report) {
                     partition: ctx.partition,
                     actorId: ctx.actorId,
                     clientId: plan.header.clientId,
+                    acceptedThrough,
+                    storageMaxCommitSeq: maxSeq,
                     subscriptions: summaries,
                 });
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/server",
-  "version": "0.30.10",
+  "version": "0.30.12",
   "description": "Syncular server: handleSyncRequest + storage/auth interfaces for the sync protocol",
   "license": "Apache-2.0",
   "author": "Benjamin Kniffler",
@@ -68,7 +68,7 @@
     "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"
   },
   "dependencies": {
-    "@syncular/core": "0.30.10"
+    "@syncular/core": "0.30.12"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.4"

package/src/errors.ts

@@ -179,6 +179,12 @@ export const ERROR_CATALOG: Readonly<Record<string, ErrorCatalogEntry>> = {
     recommendedAction: 'retryLater',
     httpStatus: 500,
   },
+  'sync.storage_stale_read': {
+    category: 'internal',
+    retryable: false,
+    recommendedAction: 'inspectServer',
+    httpStatus: 503,
+  },
   'sync.schema_not_ready': {
     category: 'internal',
     retryable: true,

package/src/events.ts

@@ -13,7 +13,7 @@
  * - Timestamps and durations come from the ctx clock where one exists, so
  *   the conformance virtual-clock discipline stays intact.
  */
-import type { WakeReason } from '@syncular/core';
+import type { ScopeMap, WakeReason } from '@syncular/core';
 
 /** One `POST /sync` request, emitted once per request after the response
  * bytes are fully produced (or the request was rejected up front). */
@@ -155,6 +155,10 @@ export interface PullSubscriptionSummary {
   readonly status: 'active' | 'revoked' | 'reset';
   /** `none` for revoked/reset sections (no data half was produced). */
   readonly mode: 'bootstrap' | 'incremental' | 'none';
+  readonly requestedScopes: ScopeMap;
+  readonly effectiveScopes: ScopeMap;
+  readonly firstCommitSeq?: number;
+  readonly lastCommitSeq?: number;
   readonly fromCursor: number;
   readonly nextCursor: number;
   readonly commits: number;
@@ -169,6 +173,8 @@ export interface PullServedEvent {
   readonly partition: string;
   readonly actorId: string;
   readonly clientId: string;
+  readonly acceptedThrough: number;
+  readonly storageMaxCommitSeq: number;
   readonly subscriptions: readonly PullSubscriptionSummary[];
 }
 

package/src/handler.ts

@@ -519,6 +519,7 @@ async function* streamResponse(
   }
   try {
     // Push half (§6): one PUSH_RESULT per PUSH_COMMIT, in request order.
+    let acceptedThrough = 0;
     for (const push of plan.pushes) {
       const processed = await processPushCommitWithTrace(
         ctx,
@@ -528,6 +529,10 @@ async function* streamResponse(
         push,
         schema,
       );
+      acceptedThrough = Math.max(
+        acceptedThrough,
+        processed.frame.commitSeq ?? 0,
+      );
       const frame = {
         ...processed.frame,
         results: processed.frame.results.map((result) => {
@@ -568,6 +573,12 @@ async function* streamResponse(
         events !== undefined ? [] : undefined;
       const limits = clampPullLimits(plan.pull);
       const maxSeq = await ctx.storage.getMaxCommitSeq(ctx.partition);
+      if (maxSeq < acceptedThrough)
+        throw syncError(
+          'sync.storage_stale_read',
+          'storage returned a commit sequence older than the accepted push; disable query caching for sync storage',
+          JSON.stringify({ acceptedThrough, storageMaxCommitSeq: maxSeq }),
+        );
       const horizonSeq = await ctx.storage.getHorizonSeq(ctx.partition);
       const prepared = await prepareSections(
         ctx,
@@ -597,6 +608,9 @@ async function* streamResponse(
         let bootstrap = false;
         let commits = 0;
         let changes = 0;
+        let effectiveScopes: ScopeMap = {};
+        let firstCommitSeq: number | undefined;
+        let lastCommitSeq: number | undefined;
         let step = await section.next();
         while (!step.done) {
           const frame = step.value as ResponseFrame;
@@ -604,9 +618,12 @@ async function* streamResponse(
             if (frame.type === 'SUB_START') {
               status = frame.status;
               bootstrap = frame.bootstrap;
+              effectiveScopes = frame.effectiveScopes;
             } else if (frame.type === 'COMMIT') {
               commits += 1;
               changes += frame.changes.length;
+              firstCommitSeq ??= frame.commitSeq;
+              lastCommitSeq = frame.commitSeq;
             }
           }
           yield encodeResponseFrame(frame, plan.wireVersion);
@@ -624,6 +641,11 @@ async function* streamResponse(
                 : bootstrap
                   ? 'bootstrap'
                   : 'incremental',
+            requestedScopes: subscription.frame.scopes,
+            effectiveScopes,
+            ...(firstCommitSeq !== undefined && lastCommitSeq !== undefined
+              ? { firstCommitSeq, lastCommitSeq }
+              : {}),
             fromCursor: subscription.frame.cursor,
             nextCursor: step.value.nextCursor,
             commits,
@@ -639,6 +661,8 @@ async function* streamResponse(
           partition: ctx.partition,
           actorId: ctx.actorId,
           clientId: plan.header.clientId,
+          acceptedThrough,
+          storageMaxCommitSeq: maxSeq,
           subscriptions: summaries,
         });
       }