@syncular/server 0.15.22 → 0.15.24

package/src/handler.ts

@@ -44,7 +44,7 @@ import {
   type SubscriptionPlan,
   subscriptionSection,
 } from './pull';
-import { processPushCommit } from './push';
+import { type ProcessedPushCommit, processPushCommitWithTrace } from './push';
 import type { CompiledSchema } from './schema';
 import { compileSchema } from './schema';
 import { computeEffective, type ResolvedScopes } from './scopes';
@@ -339,8 +339,9 @@ function emitPushEvent(
   ctx: SyncRequestContext,
   clientId: string,
   push: PushCommitFrame,
-  frame: PushResultFrame,
+  processed: ProcessedPushCommit,
 ): void {
+  const { frame } = processed;
   const base = {
     atMs: clockOf(ctx)(),
     partition: ctx.partition,
@@ -354,7 +355,7 @@ function emitPushEvent(
       type: 'push.applied',
       ...base,
       ...(frame.commitSeq !== undefined ? { commitSeq: frame.commitSeq } : {}),
-      replay: frame.status === 'cached',
+      replay: processed.replayed,
     });
     return;
   }
@@ -365,6 +366,13 @@ function emitPushEvent(
       type: 'push.conflicted',
       ...base,
       opIndex: record.opIndex,
+      replay: processed.replayed,
+      ...(processed.recordedAtMs !== undefined
+        ? { recordedAtMs: processed.recordedAtMs }
+        : {}),
+      ...(processed.cacheIdentity !== undefined
+        ? { cacheIdentity: processed.cacheIdentity }
+        : {}),
     });
     return;
   }
@@ -376,6 +384,13 @@ function emitPushEvent(
         ? record.code
         : 'sync.invalid_request',
     opIndex: record?.opIndex ?? 0,
+    replay: processed.replayed,
+    ...(processed.recordedAtMs !== undefined
+      ? { recordedAtMs: processed.recordedAtMs }
+      : {}),
+    ...(processed.cacheIdentity !== undefined
+      ? { cacheIdentity: processed.cacheIdentity }
+      : {}),
   });
 }
 
@@ -423,15 +438,16 @@ async function* streamResponse(
   try {
     // Push half (§6): one PUSH_RESULT per PUSH_COMMIT, in request order.
     for (const push of plan.pushes) {
-      const frame = await processPushCommit(
+      const processed = await processPushCommitWithTrace(
         ctx,
         schema,
         plan.resolved,
         plan.header.clientId,
         push,
       );
+      const { frame } = processed;
       if (events !== undefined) {
-        emitPushEvent(events, ctx, plan.header.clientId, push, frame);
+        emitPushEvent(events, ctx, plan.header.clientId, push, processed);
       }
       yield encodeResponseFrame(frame);
       const details = pushResultDetailsFrame(frame);

package/src/postgres-storage.ts

@@ -193,6 +193,12 @@ function serializePushResult(result: StoredPushResult): unknown {
   return {
     status: result.status,
     ...(result.commitSeq !== undefined ? { commitSeq: result.commitSeq } : {}),
+    ...(result.recordedAtMs !== undefined
+      ? { recordedAtMs: result.recordedAtMs }
+      : {}),
+    ...(result.cacheIdentity !== undefined
+      ? { cacheIdentity: result.cacheIdentity }
+      : {}),
     results: result.results.map((record) => {
       if (record.status === 'conflict') {
         return {
@@ -223,6 +229,8 @@ function deserializePushResult(value: unknown): StoredPushResult {
   const parsed = value as {
     status: 'applied' | 'rejected';
     commitSeq?: number;
+    recordedAtMs?: number;
+    cacheIdentity?: string;
     results: SerializedResult[];
   };
   const results: PushOperationResult[] = parsed.results.map((record) => {
@@ -251,6 +259,12 @@ function deserializePushResult(value: unknown): StoredPushResult {
   return {
     status: parsed.status,
     ...(parsed.commitSeq !== undefined ? { commitSeq: parsed.commitSeq } : {}),
+    ...(parsed.recordedAtMs !== undefined
+      ? { recordedAtMs: parsed.recordedAtMs }
+      : {}),
+    ...(parsed.cacheIdentity !== undefined
+      ? { cacheIdentity: parsed.cacheIdentity }
+      : {}),
     results,
   };
 }
@@ -425,7 +439,7 @@ class PostgresTransaction implements StorageTransaction {
   #partition: string;
   #resolveTable: (name: string) => CompiledTable;
   #open = true;
-  #commitValidationSavepoint = false;
+  #pushApplySavepoint = false;
   /** Resolves/rejects the `transaction(fn)` wrapper (see `begin`). */
   #resolve: () => void;
   #reject: (error: unknown) => void;
@@ -507,7 +521,7 @@ class PostgresTransaction implements StorageTransaction {
     );
   }
 
-  async lockPartitionForCommitValidation(): Promise<void> {
+  async lockPartitionForPush(): Promise<void> {
     this.#assertOpen();
     await this.#client.query(
       `INSERT INTO sync_partitions(partition, max_commit_seq) VALUES ($1, 0)
@@ -518,8 +532,8 @@ class PostgresTransaction implements StorageTransaction {
       'SELECT max_commit_seq FROM sync_partitions WHERE partition=$1 FOR UPDATE',
       [this.#partition],
     );
-    await this.#client.query('SAVEPOINT syncular_commit_validation_candidate');
-    this.#commitValidationSavepoint = true;
+    await this.#client.query('SAVEPOINT syncular_push_candidate');
+    this.#pushApplySavepoint = true;
   }
 
   async commitRejectedPushResult(
@@ -528,18 +542,12 @@ class PostgresTransaction implements StorageTransaction {
     result: StoredPushResult,
   ): Promise<void> {
     this.#assertOpen();
-    if (!this.#commitValidationSavepoint) {
-      throw new Error(
-        'whole-commit rejection requires its validation savepoint',
-      );
+    if (!this.#pushApplySavepoint) {
+      throw new Error('push rejection requires its apply savepoint');
     }
-    await this.#client.query(
-      'ROLLBACK TO SAVEPOINT syncular_commit_validation_candidate',
-    );
-    await this.#client.query(
-      'RELEASE SAVEPOINT syncular_commit_validation_candidate',
-    );
-    this.#commitValidationSavepoint = false;
+    await this.#client.query('ROLLBACK TO SAVEPOINT syncular_push_candidate');
+    await this.#client.query('RELEASE SAVEPOINT syncular_push_candidate');
+    this.#pushApplySavepoint = false;
     await this.putPushResult(clientId, clientCommitId, result);
     await this.commit();
   }

package/src/push.ts

@@ -750,6 +750,42 @@ function resultFrame(
   };
 }
 
+export interface ProcessedPushCommit {
+  readonly frame: PushResultFrame;
+  /** True when this request observed an already-recorded idempotency outcome. */
+  readonly replayed: boolean;
+  readonly recordedAtMs?: number;
+  readonly cacheIdentity?: string;
+}
+
+function processedPushCommit(
+  clientCommitId: string,
+  stored: StoredPushResult,
+  replayed: boolean,
+): ProcessedPushCommit {
+  return {
+    frame: resultFrame(clientCommitId, stored, replayed),
+    replayed,
+    ...(stored.recordedAtMs !== undefined
+      ? { recordedAtMs: stored.recordedAtMs }
+      : {}),
+    ...(stored.cacheIdentity !== undefined
+      ? { cacheIdentity: stored.cacheIdentity }
+      : {}),
+  };
+}
+
+function newStoredPushResult(
+  recordedAtMs: number,
+  result: Omit<StoredPushResult, 'recordedAtMs' | 'cacheIdentity'>,
+): StoredPushResult {
+  return {
+    ...result,
+    recordedAtMs,
+    cacheIdentity: crypto.randomUUID(),
+  };
+}
+
 function idempotencyCacheMissFrame(
   clientCommitId: string,
   error: SyncError,
@@ -770,32 +806,6 @@ function idempotencyCacheMissFrame(
   };
 }
 
-async function persistRejectedPushResult(
-  storage: SyncRequestContext['storage'],
-  partition: string,
-  clientId: string,
-  clientCommitId: string,
-  stored: StoredPushResult,
-): Promise<StoredPushResult> {
-  const rejectionTx = await storage.begin(partition);
-  try {
-    await rejectionTx.putPushResult(clientId, clientCommitId, stored);
-    await rejectionTx.commit();
-  } catch (error) {
-    await rejectionTx.rollback();
-    throw error;
-  }
-  const canonical = await storage.getPushResult(
-    partition,
-    clientId,
-    clientCommitId,
-  );
-  if (canonical === undefined) {
-    throw new Error('push rejection finalization did not persist an outcome');
-  }
-  return canonical;
-}
-
 export interface AppliedCommitEvent {
   readonly commit: StoredCommit;
 }
@@ -811,6 +821,23 @@ export async function processPushCommit(
   clientId: string,
   frame: PushCommitFrame,
 ): Promise<PushResultFrame> {
+  return (
+    await processPushCommitWithTrace(ctx, schema, resolved, clientId, frame)
+  ).frame;
+}
+
+/**
+ * Host-observable variant of `processPushCommit`. The SSP2 wire frame keeps
+ * rejected replays as `status: rejected`; this companion result preserves the
+ * cache provenance needed by structured events and server helpers.
+ */
+export async function processPushCommitWithTrace(
+  ctx: SyncRequestContext,
+  schema: CompiledSchema,
+  resolved: ResolvedScopes,
+  clientId: string,
+  frame: PushCommitFrame,
+): Promise<ProcessedPushCommit> {
   const { storage, partition } = ctx;
   let persisted: StoredPushResult | undefined;
   try {
@@ -826,12 +853,15 @@ export async function processPushCommit(
     ) {
       // §6.3: answer the retryable cache-miss for this commit rather than
       // re-applying. Not persisted — a retry may find a readable record.
-      return idempotencyCacheMissFrame(frame.clientCommitId, error);
+      return {
+        frame: idempotencyCacheMissFrame(frame.clientCommitId, error),
+        replayed: false,
+      };
     }
     throw error;
   }
   if (persisted !== undefined) {
-    return resultFrame(frame.clientCommitId, persisted, true);
+    return processedPushCommit(frame.clientCommitId, persisted, true);
   }
 
   const createdAtMs = clockOf(ctx)();
@@ -840,41 +870,49 @@ export async function processPushCommit(
   const validators = ctx.validators;
   const commitValidator = ctx.commitValidator;
   const tx = await storage.begin(partition);
+  const lockPartitionForPush =
+    tx.lockPartitionForPush?.bind(tx) ??
+    tx.lockPartitionForCommitValidation?.bind(tx);
   const commitRejectedPushResult = tx.commitRejectedPushResult?.bind(tx);
   try {
-    if (commitValidator !== undefined) {
-      if (
-        tx.lockPartitionForCommitValidation === undefined ||
-        commitRejectedPushResult === undefined
-      ) {
-        throw new Error(
-          'storage transaction does not support atomic whole-commit validation finalization',
-        );
-      }
-      await tx.lockPartitionForCommitValidation();
-      // The optimistic lookup above may have raced another request for the
-      // same idempotency key. Re-check after acquiring partition serialization
-      // so a concurrent duplicate never reruns the aggregate validator.
-      try {
-        const serializedPersisted = await storage.getPushResult(
-          partition,
-          clientId,
+    if (
+      lockPartitionForPush === undefined ||
+      commitRejectedPushResult === undefined
+    ) {
+      throw new Error(
+        'storage transaction does not support serialized push apply and atomic rejection finalization',
+      );
+    }
+    await lockPartitionForPush();
+    // The optimistic lookup above may have raced another delivery. Re-check
+    // only after acquiring partition serialization and before any operation
+    // read, validation, merge, or staged write.
+    try {
+      const serializedPersisted = await storage.getPushResult(
+        partition,
+        clientId,
+        frame.clientCommitId,
+      );
+      if (serializedPersisted !== undefined) {
+        await tx.rollback();
+        return processedPushCommit(
           frame.clientCommitId,
+          serializedPersisted,
+          true,
         );
-        if (serializedPersisted !== undefined) {
-          await tx.rollback();
-          return resultFrame(frame.clientCommitId, serializedPersisted, true);
-        }
-      } catch (error) {
-        if (
-          error instanceof SyncError &&
-          error.code === 'sync.idempotency_cache_miss'
-        ) {
-          await tx.rollback();
-          return idempotencyCacheMissFrame(frame.clientCommitId, error);
-        }
-        throw error;
       }
+    } catch (error) {
+      if (
+        error instanceof SyncError &&
+        error.code === 'sync.idempotency_cache_miss'
+      ) {
+        await tx.rollback();
+        return {
+          frame: idempotencyCacheMissFrame(frame.clientCommitId, error),
+          replayed: false,
+        };
+      }
+      throw error;
     }
     const results: PushOperationResult[] = [];
     const changes: NewChange[] = [];
@@ -923,36 +961,28 @@ export async function processPushCommit(
     if (terminated !== undefined) {
       // §6.3 rejected: only the terminating operation's record; §6.4:
       // every write of the commit rolls back.
-      const stored: StoredPushResult = {
+      const stored = newStoredPushResult(createdAtMs, {
         status: 'rejected',
         results: [terminated],
-      };
-      if (commitValidator !== undefined) {
-        // Discard candidate rows and persist the rejection while retaining the
-        // same partition lock. This closes the duplicate-request race between
-        // rollback and the durable idempotency outcome.
-        if (commitRejectedPushResult === undefined) {
-          throw new Error(
-            'storage transaction lost whole-commit rejection finalization support',
-          );
-        }
-        await commitRejectedPushResult(clientId, frame.clientCommitId, stored);
-      } else {
-        await tx.rollback();
-        const canonical = await persistRejectedPushResult(
-          storage,
-          partition,
-          clientId,
-          frame.clientCommitId,
-          stored,
-        );
-        return resultFrame(
-          frame.clientCommitId,
-          canonical,
-          canonical !== stored,
+      });
+      // Discard candidates and persist the rejection while retaining the same
+      // partition lock. There is no unlock gap in which a duplicate can rerun.
+      await commitRejectedPushResult(clientId, frame.clientCommitId, stored);
+      const canonical = await storage.getPushResult(
+        partition,
+        clientId,
+        frame.clientCommitId,
+      );
+      if (canonical === undefined) {
+        throw new Error(
+          'push rejection finalization did not persist an outcome',
         );
       }
-      return resultFrame(frame.clientCommitId, stored, false);
+      return processedPushCommit(
+        frame.clientCommitId,
+        canonical,
+        canonical.cacheIdentity !== stored.cacheIdentity,
+      );
     }
 
     const commitSeq = await tx.appendCommit({
@@ -962,7 +992,11 @@ export async function processPushCommit(
       createdAtMs,
       changes,
     });
-    const stored: StoredPushResult = { status: 'applied', commitSeq, results };
+    const stored = newStoredPushResult(createdAtMs, {
+      status: 'applied',
+      commitSeq,
+      results,
+    });
     await tx.putPushResult(clientId, frame.clientCommitId, stored);
     await tx.commit();
     if (ctx.realtime !== undefined && changes.length > 0) {
@@ -973,11 +1007,10 @@ export async function processPushCommit(
         changes,
       });
     }
-    return resultFrame(frame.clientCommitId, stored, false);
+    return processedPushCommit(frame.clientCommitId, stored, false);
   } catch (error) {
-    await tx.rollback();
     if (error instanceof StorageConstraintError) {
-      const stored: StoredPushResult = {
+      const stored = newStoredPushResult(createdAtMs, {
         status: 'rejected',
         results: [
           {
@@ -988,16 +1021,31 @@ export async function processPushCommit(
             retryable: false,
           },
         ],
-      };
-      const canonical = await persistRejectedPushResult(
-        storage,
+      });
+      if (commitRejectedPushResult === undefined) {
+        await tx.rollback();
+        throw new Error(
+          'storage transaction lost atomic push rejection finalization support',
+        );
+      }
+      await commitRejectedPushResult(clientId, frame.clientCommitId, stored);
+      const canonical = await storage.getPushResult(
         partition,
         clientId,
         frame.clientCommitId,
-        stored,
       );
-      return resultFrame(frame.clientCommitId, canonical, canonical !== stored);
+      if (canonical === undefined) {
+        throw new Error(
+          'push rejection finalization did not persist an outcome',
+        );
+      }
+      return processedPushCommit(
+        frame.clientCommitId,
+        canonical,
+        canonical.cacheIdentity !== stored.cacheIdentity,
+      );
     }
+    await tx.rollback();
     throw error;
   }
 }

package/src/realtime.ts

@@ -30,53 +30,26 @@ import {
   type ScopeMap,
   type WakeReason,
 } from '@syncular/core';
-import type {
-  LeaseConfig,
-  ResolveScopes,
-  ServerLimits,
-  SyncRequestContext,
-} from './context';
+import type { SyncRequestContext, SyncServerConfig } from './context';
 import { RESOLVER_OUTAGE } from './context';
 import { SyncError, syncError } from './errors';
 import { emitEvent, type SyncularServerEvents } from './events';
 import { createSyncResponseStream } from './handler';
-import type { ServerSchema } from './schema';
 import { type CompiledSchema, compileSchema } from './schema';
 import {
   computeEffective,
   matchesEffective,
   type ResolvedScopes,
 } from './scopes';
-import type { SegmentStore } from './segment-store';
-import type { SegmentUrlConfig } from './signed-url';
 import type { ServerStorage, StoredCommit } from './storage';
-import type { CommitValidator, ValidatorRegistry } from './validate';
 
-export interface RealtimeHubConfig {
-  readonly schema: ServerSchema;
-  readonly storage: ServerStorage;
-  readonly resolveScopes: ResolveScopes;
-  /** §6.7 validators used by sync rounds carried over this socket. */
-  readonly validators?: ValidatorRegistry;
-  /** §6.8 whole-commit validator shared with HTTP sync rounds. */
-  readonly commitValidator?: CommitValidator;
-  readonly clock?: () => number;
+/**
+ * Realtime adds fanout/presence tuning to the canonical sync-server config;
+ * socket rounds must never have a narrower push/pull capability set than HTTP.
+ */
+export interface RealtimeHubConfig extends Omit<SyncServerConfig, 'realtime'> {
   /** Deltas larger than this become `delta-too-large` wake-ups (§8.2). */
   readonly maxDeltaBytes?: number;
-  /** Optional structured-events sink (`realtime.*` events). */
-  readonly events?: SyncularServerEvents;
-  /**
-   * Segment store for sync rounds over the socket (§8.7). Without it a
-   * socket round fails loudly with an in-band ERROR — provide the same
-   * store the HTTP binding uses (one handler, two framings).
-   */
-  readonly segments?: SegmentStore;
-  /** Request limits for socket rounds; defaults match the HTTP binding. */
-  readonly limits?: Partial<ServerLimits>;
-  readonly signedUrls?: SegmentUrlConfig;
-  /** §7.3 auth leases for socket sync rounds (§8.7) — same config the
-   * HTTP binding uses, so rounds over the socket are lease-aware too. */
-  readonly leases?: LeaseConfig;
   /**
    * §8.6 presence: cap on the serialized size (bytes) of a published
    * presence document. An over-cap publish is rejected loudly to the
@@ -494,9 +467,11 @@ export class RealtimeSession {
    * round's request byte stream (§8.7). Synchronous entry — assembly and
    * violation detection happen inline so a pipelined chunk arriving
    * while a response streams is caught deterministically; the round
-   * itself runs async once the request is complete.
+   * itself runs async once the request is complete. The returned promise, when
+   * present, resolves only after response streaming and registration refresh;
+   * coordinated hosts await it to retain their partition FIFO through commit.
    */
-  handleBinary(bytes: Uint8Array): void {
+  handleBinary(bytes: Uint8Array): Promise<void> | undefined {
     if (bytes.length === 0) return;
     if (bytes[0] !== REALTIME_TAG_ROUND) {
       // §8.7: client→server tags other than 0x01 — a broken client.
@@ -531,7 +506,7 @@ export class RealtimeSession {
     }
     const token = Symbol('round');
     this.#activeRound = token;
-    void this.#runRound(done.message.slice(), token);
+    return this.#runRound(done.message.slice(), token);
   }
 
   /** Drive the shared handler and stream the response back (§8.7). */
@@ -914,7 +889,10 @@ export class RealtimeHub {
    * the same shape the HTTP adapter builds, so the round drives the
    * SAME handler with zero semantic divergence.
    */
-  requestContext(session: RealtimeSession): SyncRequestContext {
+  requestContextFor(identity: {
+    readonly partition: string;
+    readonly actorId: string;
+  }): SyncRequestContext {
     const segments = this.#config.segments;
     if (segments === undefined) {
       // Fail loud (§8.7): a hub serving socket rounds needs the same
@@ -925,12 +903,21 @@ export class RealtimeHub {
       );
     }
     return {
-      partition: session.partition,
-      actorId: session.actorId,
+      partition: identity.partition,
+      actorId: identity.actorId,
       schema: this.#config.schema,
       storage: this.#config.storage,
       segments,
       resolveScopes: this.#config.resolveScopes,
+      ...(this.#config.blobs !== undefined
+        ? { blobs: this.#config.blobs }
+        : {}),
+      ...(this.#config.maxBlobBytes !== undefined
+        ? { maxBlobBytes: this.#config.maxBlobBytes }
+        : {}),
+      ...(this.#config.crdtMergers !== undefined
+        ? { crdtMergers: this.#config.crdtMergers }
+        : {}),
       ...(this.#config.validators !== undefined
         ? { validators: this.#config.validators }
         : {}),
@@ -946,6 +933,15 @@ export class RealtimeHub {
       ...(this.#config.signedUrls !== undefined
         ? { signedUrls: this.#config.signedUrls }
         : {}),
+      ...(this.#config.blobSignedUrls !== undefined
+        ? { blobSignedUrls: this.#config.blobSignedUrls }
+        : {}),
+      ...(this.#config.blobUploadUrls !== undefined
+        ? { blobUploadUrls: this.#config.blobUploadUrls }
+        : {}),
+      ...(this.#config.sqliteImageBuilder !== undefined
+        ? { sqliteImageBuilder: this.#config.sqliteImageBuilder }
+        : {}),
       ...(this.#config.leases !== undefined
         ? { leases: this.#config.leases }
         : {}),
@@ -956,6 +952,10 @@ export class RealtimeHub {
     };
   }
 
+  requestContext(session: RealtimeSession): SyncRequestContext {
+    return this.requestContextFor(session);
+  }
+
   /**
    * Register a connected socket (§8.1): load the client's last pull's
    * subscription list, resolve + intersect scopes, send `hello`.