@syncular/server 0.0.6-185 → 0.0.6-201

package/src/pull.ts

@@ -41,7 +41,37 @@ import {
 import { resolveEffectiveScopesForSubscriptions } from './subscriptions/resolve';
 
 const defaultScopeCache = createMemoryScopeCache();
-const MAX_SNAPSHOT_BUNDLE_ROW_FRAME_BYTES = 512 * 1024;
+const DEFAULT_MAX_SNAPSHOT_BUNDLE_ROW_FRAME_BYTES = 512 * 1024;
+const MAX_ADAPTIVE_SNAPSHOT_BUNDLE_ROW_FRAME_BYTES = 4 * 1024 * 1024;
+const DEFAULT_INLINE_SNAPSHOT_ROW_FRAME_BYTES = 256 * 1024;
+const EMPTY_SNAPSHOT_ROW_FRAMES = encodeSnapshotRows([]);
+
+interface PullBootstrapTimings {
+  snapshotQueryMs: number;
+  rowFrameEncodeMs: number;
+  chunkCacheLookupMs: number;
+  chunkGzipMs: number;
+  chunkHashMs: number;
+  chunkPersistMs: number;
+}
+
+interface SnapshotChunkEncodeResult {
+  body: Uint8Array;
+  sha256: string;
+  gzipMs: number;
+  hashMs: number;
+}
+
+function createPullBootstrapTimings(): PullBootstrapTimings {
+  return {
+    snapshotQueryMs: 0,
+    rowFrameEncodeMs: 0,
+    chunkCacheLookupMs: 0,
+    chunkGzipMs: 0,
+    chunkHashMs: 0,
+    chunkPersistMs: 0,
+  };
+}
 
 function concatByteChunks(chunks: readonly Uint8Array[]): Uint8Array {
   if (chunks.length === 1) {
@@ -186,28 +216,73 @@ async function gzipByteChunks(
   return gzipBytes(concatByteChunks(chunks));
 }
 
-async function gzipByteChunksToStream(chunks: readonly Uint8Array[]): Promise<{
+async function encodeCompressedSnapshotChunk(
+  chunks: readonly Uint8Array[]
+): Promise<SnapshotChunkEncodeResult> {
+  const gzipStartedAt = Date.now();
+  const gzipPromise = gzipByteChunks(chunks).then((body) => ({
+    body,
+    gzipMs: Math.max(0, Date.now() - gzipStartedAt),
+  }));
+  const hashStartedAt = Date.now();
+  const hashPromise = sha256HexFromByteChunks(chunks).then((sha256) => ({
+    sha256,
+    hashMs: Math.max(0, Date.now() - hashStartedAt),
+  }));
+  const [{ body, gzipMs }, { sha256, hashMs }] = await Promise.all([
+    gzipPromise,
+    hashPromise,
+  ]);
+  return { body, sha256, gzipMs, hashMs };
+}
+
+async function encodeCompressedSnapshotChunkToStream(
+  chunks: readonly Uint8Array[]
+): Promise<{
   stream: ReadableStream<Uint8Array>;
-  byteLength?: number;
+  byteLength: number;
+  sha256: string;
+  gzipMs: number;
+  hashMs: number;
 }> {
-  if (typeof CompressionStream !== 'undefined') {
-    const source = byteChunksToStream(chunks).pipeThrough(
-      new CompressionStream('gzip')
-    );
-    return {
-      stream: bufferSourceStreamToUint8ArrayStream(source),
-    };
-  }
-
-  const compressed = await gzipBytes(concatByteChunks(chunks));
+  const encoded = await encodeCompressedSnapshotChunk(chunks);
   return {
     stream: bufferSourceStreamToUint8ArrayStream(
-      byteChunksToStream([compressed])
+      byteChunksToStream([encoded.body])
     ),
-    byteLength: compressed.length,
+    byteLength: encoded.body.length,
+    sha256: encoded.sha256,
+    gzipMs: encoded.gzipMs,
+    hashMs: encoded.hashMs,
   };
 }
 
+function resolveSnapshotBundleMaxBytes(args: {
+  configuredMaxBytes?: number;
+  pageRowCount: number;
+  pageRowFrameBytes: number;
+}): number {
+  if (
+    typeof args.configuredMaxBytes === 'number' &&
+    Number.isFinite(args.configuredMaxBytes) &&
+    args.configuredMaxBytes > 0
+  ) {
+    return Math.max(1, args.configuredMaxBytes);
+  }
+
+  if (args.pageRowCount <= 0 || args.pageRowFrameBytes <= 0) {
+    return DEFAULT_MAX_SNAPSHOT_BUNDLE_ROW_FRAME_BYTES;
+  }
+
+  return Math.max(
+    DEFAULT_MAX_SNAPSHOT_BUNDLE_ROW_FRAME_BYTES,
+    Math.min(
+      MAX_ADAPTIVE_SNAPSHOT_BUNDLE_ROW_FRAME_BYTES,
+      args.pageRowFrameBytes
+    )
+  );
+}
+
 export interface PullResult {
   response: SyncPullResponse;
   /**
@@ -217,6 +292,8 @@ export interface PullResult {
   effectiveScopes: ScopeValues;
   /** Minimum nextCursor across active subscriptions (for pruning cursor tracking). */
   clientCursor: number;
+  /** Internal bootstrap timing breakdown used for benchmark-gated diagnostics. */
+  bootstrapTimings?: PullBootstrapTimings;
 }
 
 interface PendingExternalChunkWrite {
@@ -419,6 +496,7 @@ async function readLatestExternalCommitByTable<DB extends SyncCoreDb>(
     .select((eb) => eb.fn.max('tc.commit_seq').as('latest_commit_seq'))
     .where('tc.partition_id', '=', args.partitionId)
     .where('cm.client_id', '=', EXTERNAL_CLIENT_ID)
+    .where('cm.change_count', '=', 0)
     .where('tc.commit_seq', '>', args.afterCursor)
     .where('tc.table', 'in', tableNames)
     .groupBy('tc.table')
@@ -480,7 +558,7 @@ export async function pull<
           request.limitSnapshotRows,
           1000,
           1,
-          5000
+          20000
         );
         const maxSnapshotPages = sanitizeLimit(
           request.maxSnapshotPages,
@@ -490,6 +568,7 @@ export async function pull<
         );
         const dedupeRows = request.dedupeRows === true;
         const pendingExternalChunkWrites: PendingExternalChunkWrite[] = [];
+        const bootstrapTimings = createPullBootstrapTimings();
 
         // Resolve effective scopes for each subscription
         const resolved = await resolveEffectiveScopesForSubscriptions({
@@ -581,6 +660,11 @@ export async function pull<
                 args.handlers,
                 sub.table
               ).map((handler) => handler.table);
+              const preferInlineBootstrapSnapshot =
+                cursor >= 0 ||
+                sub.bootstrapState != null ||
+                (latestExternalCommitForTable !== undefined &&
+                  latestExternalCommitForTable > cursor);
 
               const initState: SyncBootstrapState = {
                 asOfCommitSeq: maxCommitSeq,
@@ -636,17 +720,29 @@ export async function pull<
                 ttlMs: number;
                 rowFrameByteLength: number;
                 rowFrameParts: Uint8Array[];
+                inlineRows: unknown[] | null;
               }
 
               const flushSnapshotBundle = async (
                 bundle: SnapshotBundle
               ): Promise<void> => {
+                if (bundle.inlineRows) {
+                  snapshots.push({
+                    table: bundle.table,
+                    rows: bundle.inlineRows,
+                    isFirstPage: bundle.isFirstPage,
+                    isLastPage: bundle.isLastPage,
+                  });
+                  return;
+                }
+
                 const nowIso = new Date().toISOString();
                 const bundleRowLimit = Math.max(
                   1,
                   limitSnapshotRows * bundle.pageCount
                 );
 
+                const cacheLookupStartedAt = Date.now();
                 const cached = await readSnapshotChunkRefByPageKey(trx, {
                   partitionId,
                   scopeKey: cacheKey,
@@ -658,6 +754,10 @@ export async function pull<
                   compression: SYNC_SNAPSHOT_CHUNK_COMPRESSION,
                   nowIso,
                 });
+                bootstrapTimings.chunkCacheLookupMs += Math.max(
+                  0,
+                  Date.now() - cacheLookupStartedAt
+                );
 
                 let chunkRef = cached;
                 if (!chunkRef) {
@@ -689,13 +789,13 @@ export async function pull<
                     });
                     return;
                   }
-                  const sha256 = await sha256HexFromByteChunks(
-                    bundle.rowFrameParts
-                  );
-                  const compressedBody = await gzipByteChunks(
+                  const encodedChunk = await encodeCompressedSnapshotChunk(
                     bundle.rowFrameParts
                   );
+                  bootstrapTimings.chunkGzipMs += encodedChunk.gzipMs;
+                  bootstrapTimings.chunkHashMs += encodedChunk.hashMs;
                   const chunkId = randomId();
+                  const chunkPersistStartedAt = Date.now();
                   chunkRef = await insertSnapshotChunk(trx, {
                     chunkId,
                     partitionId,
@@ -706,10 +806,14 @@ export async function pull<
                     rowLimit: bundleRowLimit,
                     encoding: SYNC_SNAPSHOT_CHUNK_ENCODING,
                     compression: SYNC_SNAPSHOT_CHUNK_COMPRESSION,
-                    sha256,
-                    body: compressedBody,
+                    sha256: encodedChunk.sha256,
+                    body: encodedChunk.body,
                     expiresAt,
                   });
+                  bootstrapTimings.chunkPersistMs += Math.max(
+                    0,
+                    Date.now() - chunkPersistStartedAt
+                  );
                 }
 
                 snapshots.push({
@@ -750,7 +854,7 @@ export async function pull<
                   if (activeBundle) {
                     await flushSnapshotBundle(activeBundle);
                   }
-                  const bundleHeader = encodeSnapshotRows([]);
+                  const bundleHeader = EMPTY_SNAPSHOT_ROW_FRAMES;
                   activeBundle = {
                     table: nextTableName,
                     startCursor: nextState.rowCursor,
@@ -761,9 +865,11 @@ export async function pull<
                       tableHandler.snapshotChunkTtlMs ?? 24 * 60 * 60 * 1000,
                     rowFrameByteLength: bundleHeader.length,
                     rowFrameParts: [bundleHeader],
+                    inlineRows: null,
                   };
                 }
 
+                const snapshotQueryStartedAt = Date.now();
                 const page: { rows: unknown[]; nextCursor: string | null } =
                   await tableHandler.snapshot(
                     {
@@ -776,15 +882,29 @@ export async function pull<
                     },
                     sub.params
                   );
+                bootstrapTimings.snapshotQueryMs += Math.max(
+                  0,
+                  Date.now() - snapshotQueryStartedAt
+                );
 
+                const rowFrameEncodeStartedAt = Date.now();
                 const rowFrames = encodeSnapshotRowFrames(page.rows ?? []);
+                bootstrapTimings.rowFrameEncodeMs += Math.max(
+                  0,
+                  Date.now() - rowFrameEncodeStartedAt
+                );
+                const bundleMaxBytes = resolveSnapshotBundleMaxBytes({
+                  configuredMaxBytes: tableHandler.snapshotBundleMaxBytes,
+                  pageRowCount: page.rows?.length ?? 0,
+                  pageRowFrameBytes: rowFrames.length,
+                });
                 if (
                   activeBundle.pageCount > 0 &&
                   activeBundle.rowFrameByteLength + rowFrames.length >
-                    MAX_SNAPSHOT_BUNDLE_ROW_FRAME_BYTES
+                    bundleMaxBytes
                 ) {
                   await flushSnapshotBundle(activeBundle);
-                  const bundleHeader = encodeSnapshotRows([]);
+                  const bundleHeader = EMPTY_SNAPSHOT_ROW_FRAMES;
                   activeBundle = {
                     table: nextTableName,
                     startCursor: nextState.rowCursor,
@@ -795,8 +915,20 @@ export async function pull<
                       tableHandler.snapshotChunkTtlMs ?? 24 * 60 * 60 * 1000,
                     rowFrameByteLength: bundleHeader.length,
                     rowFrameParts: [bundleHeader],
+                    inlineRows: null,
                   };
                 }
+
+                if (
+                  preferInlineBootstrapSnapshot &&
+                  activeBundle.pageCount === 0 &&
+                  page.nextCursor == null &&
+                  rowFrames.length <= DEFAULT_INLINE_SNAPSHOT_ROW_FRAME_BYTES
+                ) {
+                  activeBundle.inlineRows = page.rows ?? [];
+                } else {
+                  activeBundle.inlineRows = null;
+                }
                 activeBundle.rowFrameParts.push(rowFrames);
                 activeBundle.rowFrameByteLength += rowFrames.length;
                 activeBundle.pageCount += 1;
@@ -1040,6 +1172,7 @@ export async function pull<
             pendingExternalChunkWrites,
             4,
             async (pending) => {
+              const cacheLookupStartedAt = Date.now();
               let chunkRef = await readSnapshotChunkRefByPageKey(db, {
                 partitionId: pending.cacheLookup.partitionId,
                 scopeKey: pending.cacheLookup.scopeKey,
@@ -1050,14 +1183,25 @@ export async function pull<
                 encoding: SYNC_SNAPSHOT_CHUNK_ENCODING,
                 compression: SYNC_SNAPSHOT_CHUNK_COMPRESSION,
               });
+              bootstrapTimings.chunkCacheLookupMs += Math.max(
+                0,
+                Date.now() - cacheLookupStartedAt
+              );
 
               if (!chunkRef) {
-                const sha256 = await sha256HexFromByteChunks(
-                  pending.rowFrameParts
-                );
                 if (chunkStorage.storeChunkStream) {
-                  const { stream: bodyStream, byteLength } =
-                    await gzipByteChunksToStream(pending.rowFrameParts);
+                  const {
+                    stream: bodyStream,
+                    byteLength,
+                    sha256,
+                    gzipMs,
+                    hashMs,
+                  } = await encodeCompressedSnapshotChunkToStream(
+                    pending.rowFrameParts
+                  );
+                  bootstrapTimings.chunkGzipMs += gzipMs;
+                  bootstrapTimings.chunkHashMs += hashMs;
+                  const chunkPersistStartedAt = Date.now();
                   chunkRef = await chunkStorage.storeChunkStream({
                     partitionId: pending.cacheLookup.partitionId,
                     scopeKey: pending.cacheLookup.scopeKey,
@@ -1072,10 +1216,17 @@ export async function pull<
                     bodyStream,
                     expiresAt: pending.expiresAt,
                   });
+                  bootstrapTimings.chunkPersistMs += Math.max(
+                    0,
+                    Date.now() - chunkPersistStartedAt
+                  );
                 } else {
-                  const compressedBody = await gzipByteChunks(
+                  const encodedChunk = await encodeCompressedSnapshotChunk(
                     pending.rowFrameParts
                   );
+                  bootstrapTimings.chunkGzipMs += encodedChunk.gzipMs;
+                  bootstrapTimings.chunkHashMs += encodedChunk.hashMs;
+                  const chunkPersistStartedAt = Date.now();
                   chunkRef = await chunkStorage.storeChunk({
                     partitionId: pending.cacheLookup.partitionId,
                     scopeKey: pending.cacheLookup.scopeKey,
@@ -1085,10 +1236,14 @@ export async function pull<
                     rowLimit: pending.cacheLookup.rowLimit,
                     encoding: SYNC_SNAPSHOT_CHUNK_ENCODING,
                     compression: SYNC_SNAPSHOT_CHUNK_COMPRESSION,
-                    sha256,
-                    body: compressedBody,
+                    sha256: encodedChunk.sha256,
+                    body: encodedChunk.body,
                     expiresAt: pending.expiresAt,
                   });
+                  bootstrapTimings.chunkPersistMs += Math.max(
+                    0,
+                    Date.now() - chunkPersistStartedAt
+                  );
                 }
               }
 
@@ -1106,6 +1261,14 @@ export async function pull<
         span.setAttribute('commit_count', stats.commitCount);
         span.setAttribute('change_count', stats.changeCount);
         span.setAttribute('snapshot_page_count', stats.snapshotPageCount);
+        span.setAttributes({
+          bootstrap_snapshot_query_ms: bootstrapTimings.snapshotQueryMs,
+          bootstrap_row_frame_encode_ms: bootstrapTimings.rowFrameEncodeMs,
+          bootstrap_chunk_cache_lookup_ms: bootstrapTimings.chunkCacheLookupMs,
+          bootstrap_chunk_gzip_ms: bootstrapTimings.chunkGzipMs,
+          bootstrap_chunk_hash_ms: bootstrapTimings.chunkHashMs,
+          bootstrap_chunk_persist_ms: bootstrapTimings.chunkPersistMs,
+        });
         span.setStatus('ok');
 
         recordPullMetrics({
@@ -1115,7 +1278,10 @@ export async function pull<
           stats,
         });
 
-        return result;
+        return {
+          ...result,
+          bootstrapTimings,
+        };
       } catch (error) {
         const durationMs = Math.max(0, Date.now() - startedAtMs);